Bizum

Introduction

Bizum is an instant payment service using mobile banking. It lets you send money to other people and pay certain businesses. Bizum links the client’s phone number to a bank account. 

For your business to use Bizum with Addon Payments, you must:

  • Have Bizum activated for your merchant. If you have any questions or need to activate it, contact your bank’s account manager.
  • Ask the Addon Payments support team to activate and set up Bizum on your Virtual POS. 

Your customers must:

  • Have Bizum activated and properly set up and linked. If customers have questions about Bizum, they should check out the Frequently Asked Questions on the Bizum website. 

Here, you can download the Bizum Rules PDF.

Payment typeImmediate payments
Countries availableSpain
Currencies availableEuro
Minimum totalDepends on the ordering entity
Maximum totalDepends on the ordering entity
Need redirect?Yes, for customers without RTP or if you don’t know the curstomer’s phone number
Two-step payment allowed?Yes
Refunds allowed?Yes, total and partial amounts through BackOffice or H2H request

Bizum integration lets your business carry out several operations:

  1. RTP (Ready To Pay): an operation the bank can activate for the customer. It makes payment easier because the customer only has to authorise the operation in their banking app. The request must include a phone number.
  2. Two-step payment (authentication + authorization with capture): In the first phase, the customer authenticates payment, but the amount isn’t deducted from their account yet. In the second phase, you capture (or release) the transaction amount.
  3. Refunds: Allows you to refund the full or partial amount of the transaction.  

Finally, you have a Postman collection where you can test the different Bizum operations:

Credentials for Bizum integration testing

In the Addon Payments Staging environment, you can process as many transactions as you want to verify that Bizum has been properly integrated.

You need the following data to test Bizum:

  • Phone number: 700000000
  • Amount: In the Staging environment, the transaction result changes based on the amount. Here are the possible results by amount:
AmountCustomer with BizumCustomer with RTPTransaction result
Amount less than €5.00YesYesAuthorized
Amount equal to or greater than €5.00 and less than €10.00YesYesDeclined
Amount between €10.00 and €15.00YesNoAuthorized
Amount over €15.00YesNoDeclined

Environments: Staging and Production endpoints

Addon Payments has two (2) separate operating environments:

Staging environment:

  • This is the first environment you will use.
  • You can test your set-up with the credentials in the previous section.
  • This will allow you to make sure that the different situations are handled properly by your integration.
  • Real cards and accounts don’t work.

Production Environment:

  • In this environment, transactions are real.
  • You can only use real, operational cards and accounts.

Below are the endpoints by type of integration:

EnvironmentHostedHost2Host
Staginghttps://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize
https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay
Productionhttps://checkout.addonpayments.com/EPGCheckout/rest/online/tokenize
https://checkout.addonpayments.com/EPGCheckout/rest/online/pay
RequestEnvironmentURL
Request /authStaginghttps://epgjs-mep-stg.addonpayments.com/auth
Request /chargeStaginghttps://epgjs-mep-stg.addonpayments.com/charge/v2
Request /authProductionhttps://epgjs-mep.addonpayments.com/auth
Request /chargeProductionhttps://epgjs-mep.addonpayments.com/charge/v2

Hosted integration

With Addon Payments you can integrate the Bizum payment solution into redirect integrations (Hosted). This can be done via RTP (the customer authorizes from their banking app if they have this option activated) or by redirect to a Bizum URL.

On the payment cashier, you can choose to show only the Bizum payment solution or to show all the payment solutions you have available. To show only Bizum, send “paymentSolution: bizum”. If you don’t send this payment, all the payment solutions will be sent. 

Required and optional data Hosted

These are the required (R) and optional (O) parameters for a Bizum transaction via Hosted:

FieldFormatTypeDescriptionExample
merchantIdWhole number
4~7 digits		RYour merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments14983
merchantTransactionIdAlphanumeric
Max 12 characters
Min 4 characters
Does not support special characters		RThis is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order.order91684
amountNumerical with decimalsRAmount of the transaction. If the amount has decimals, the separator is a dot (.). The separator cannot be included in the thousands.127.5
currencyAlphabetical
3 characters
ISO-4217.3		RCurrency of the transactionEUR
countryAlphabetical
3 characters
ISO 4217.3		RCountry from which the transaction is sentES
customerIdAlphanumeric
Max 80 characters		RCustomer ID in your e-commerce platform.A34623
statusURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your e-commerce platform where AP will send the notification with the status of the transaction. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/status
successURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is authorized. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/success
errorURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is declined. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/error
cancelURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is cancelled during the payment process. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/cancel
awaitingURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		R (for clients with RTP)URL of your platform to which the customer is redirected if the transaction is via RTP and the customer has to authenticate their transaction in the bank application. If it is sent in the request, it will have priority over the one configured in the Addon Payments BackOffice Portal. If not sent in the request, the client will be redirected to the URL configured in the management pack.https://www.example.com/awaiting
telephoneAlphanumeric
Max 45 characters		R (for clients with RTP without spanish phone number)Phone number. No code.700000000
phoneCodeValid country codeRCountry code for the customer’s phone number. Only necessary for non-Spanish phone numbers.+33
paymentSolutionAlphanumeric
Max 45 characters		OName of the payment solution to process the transaction. If you only want the customer to see Bizum, you must include this parameter.bizum
autoCaptureBoolean
– true: Automatically capture the amount.
– false: Manual capture.		OEstablishes whether the transaction is an authorization or authentication + authorization and capture. For the latter, the merchant must capture or release afterwards.True

Authorization – without customer’s phone number

If you don’t have the customer’s phone number, you can’t put it in the request. In this case, after the request you will receive a URL to redirect the customer and complete the operation.

This URL will come in the “redirectionResponse” field. There, the customer will enter their phone number. The merchant has to wait for notification with the transaction result (accepted, cancelled, etc.). 

Request

These are some sample payment requests for Bizum without the phone number via Hosted. Remember, the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=4.00&currency
=EUR&country=ES&customerId=000001&telephone=700000000&statusURL
=https://micomercio.com/recepcion_notificacion.php?tipo?redireccion&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio
.com/url-ko.php&cancelURL=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.easypaymentgateway.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 2aoJ+ha5Ucb4JiXu775OVQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="sHibJ8BRHFklHSLBTo7siFNJFV8LUJrqpWmlj4e9a7FojO1VXAXE55yXTA/qhYR2jT32HwHat63AcF7ZqHFMgAwKfzBwZdB255ioE2hpWaDgS98Tj/RdcjyiwYhcnAmz8+8sXBUSn0sp5gJ4ZTS7aDDQ3pR34sn2KkgKtnDEGh8erCi3v9q88R/BY1P9c9Kpzk4JzsnPlFE5wb3H27XvCiluT08JvsT6TAnq+I6DWxANQLefcNDoMuYnp4z+p1I/5MvZ0nMF7Y4KQCQRPRqSxBkz4I2EM0xGA4ndLnd/kX84hUjoNQgD2Gp/1hSKjYwNc+aZBz71jC3rxr8IASgUX5pj/G7+g1kqqiHxFX5fPrM+rr0pdTHKgD80TGo/q/nqU33Q+JcgQSiq0m/A9dIjDcebp83DwEmazdZaQl9WAXuiLUK/ip/C/wHDbMq34hHrhd8c1xw81Dcc6IsLyNRJ9mxcIpRoF8rpnL2snppTl1nZvQRnp6qn+3DMAHJgsNQPiHPTpU+KCE9tPz0in3KvkBVIbT3quODP/cB7GTOFlTdfKRZRTI/sgLHBcggTaLbYFsXYQ++061fcQPLm1BdnGcvIFy8KbrCL7tiw0tIsyXBCT+ARh+pG/zA+J/7PqKfpP3B5ITQMjg/xlcFl0NdqbkRBW12z7ZQwa6eUzZUneqdXN8rk9dBXZqQsgsMmjqVVRoDWJd2szrFpVTL/YJ+TDcQqPUMH/fMra3o+xyJcSAk=="' \
--form 'integrityCheck="ff80ef8e823c52266145aa01c53bdee5beadfe5f941c2921fc7b037cd06ed605"'

After sending the POST to Addon Payments, you will receive the URL to redirect your customer: 

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize?token
=3acf6d9e-a58d-4664-b8e4-e4b924f89788&apiVersion=5

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Response

This is an example of a notification after an authorized operation. The first one informing the URL to which you must redirect the customer and the second one with the status of the transaction:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7740186</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>b3ca7ba7_96c6_4bd3_bbf8_056ab697ab08</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>PENDING</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>26</version>
  </workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7739892</message>
  <operations>
    <operation sorted-order="1">
      <amount>4.00</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"24%2F11%2F2023","Ds_Hour":"12%3A18","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11949655661825480278698394628084188","Ds_ProcessedPayMethod":"68","Ds_Control_1700824708408":"1700824708408"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>SUCCESS</status>
      <transactionId>7739892</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>5d18a222_fbd3_4a46_a1a6_b32c103ea322</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>26</version>
  </workFlowResponse>
</response>

Authorization – with customer’s phone number

If you send the customer’s phone number in the request, one of two things will happen:

  • If the customer has RTP activated, they will authorize the purchase on their banking app.
  • If the customer doesn’t have RTP activated, they will automatically be redirected to a Bizum URL to authorize the transaction. 

Regardless, the request the merchant sends is the same in both cases. 

Request

These are some sample payment requests for Bizum with the phone number via Hosted. Remember, the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=5.00&currency=EUR&country
=ES&customerId=000001&telephone=700000000&statusURL=https://micomercio
.com/recepcion_notificacion.php?tipo?redireccion&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.easypaymentgateway.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: mx3rdwlpuDA1vM14SFT5bw==' \
--form 'merchantId="12345"' \
--form 'encrypted="/kJtS1WhS33iGLIvOuv7ISPKF4D3lldTzKkEgeuuldajqZJ4jS9Nk1ZU/rpKt1pjxJeXL17eSkVfvA6QhOpnjHr5kr5EpN5zOZ/XmooMSkBN3gbRu23SIUHPuSC00b6ygyr+cU/yUlGeNOQl6OD5iDuJwWN7cV57DmXMtn0w3/4OGKHjZpP0SKBNeuNbwCQkVZ0iYB5rM5ZpRV3oulUbyau2tMGPokUvNWWGjyh6uf1b+BDyTYeINoI0oCDFsJaD6Vpjrw7C8JSSLy441SZW6/7/HEHqd39hsfpFQ7pb3y7GHo+TGGJ6BHi4SfZJ+5PwKasGdzgKvNxzWX4ozRBUpnbQNu44khf1/+NExvYluelD+ilvdkW9Qx5vzEzaO7x99tqk/zttfsq12KTDqaYIiE0y5W+QnyFy/jDPnVWxTivaJzhBqivfE6Mvt9lHC2jORgF6eC6MPStVB84NKvmcyUGSfUgdKoKu1ssT/zSc7IIS8y+Absb6CTX8ErteJCGmywbwu8OAP2+4R67pf/Kzm7XQHx3qgjlULs9TjDN2i+Bc4BV5hjC/ZVwV73R05FD/JufrWMAProhqNMIvRdonGWrjhVvASVTfyRPIhzRdiQD+y92IlU1YHQuapUJAxs7NVOf8rUM9SBxu3IH9JXj7cOP5UkzNVKSqyj0P1AYIlZXo/8e7wCT6tW5Yz1f6xQrAj7RCJXYgaiLpTFzNe9VDkGEYMCF5CI6z2eZmPQBFMsVJtroV3mvgBhRdK6j64utR' \
--form 'integrityCheck="e55c1dae947b376645b8fbd7f3612f0cf63045236c80b643f8335d3c4050ec70"'

After sending the POST to Addon Payments, you will receive the URL to redirect your customer: 

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize?token
=2166f73d-6412-48d3-b440-6da9a961594b&apiVersion=5

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Plus, you should add the optional ones:

  • telephone: customer’s phone number (without country code).
  • awaitingURL: Waiting URL for your business where you can redirect the customer while authenticating the transaction in their bank application.
  • phoneCode: Only for non-Spanish phone numbers.

Response

The notifications you receive depend on whether the customer has RTP activated.

If they have it activated, you will receive 2 notifications: The first one indicating that the transaction is pending authentication by the customer, and the second one indicating the status (success, cancelled, etc.) of the transaction.

If they don’t have it activated, you will receive two notifications: the first with a URL where the customer will be redirected and the second with the transaction status. 

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
	<message>WorkFlow has finished successfully, for transaction Id: 646268629</message>
	<operations>
		<operation sorted-order="1">
			<amount>1.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_RtpStatus":"OK","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"Operacion realizada correctamente","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"20546099","Ds_Currency":"978","Ds_Amount":"100"}</details>
			<merchantTransactionId>20546099</merchantTransactionId>
			<message>Bizum RTP CHECK result : OK</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>20546099</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>COMPLETED</status>
			<transactionId>646268629</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>8ff71c04_63a7_4adb_a042_7bf4fa4a77cc</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>1.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_Amount":"100","Ds_Currency":"978","Ds_Order":"20546099","Ds_MerchantCode":"008043853","Ds_Terminal":"50","Ds_Response":"9998","Ds_AuthorisationCode":"","Ds_TransactionType":"0","Ds_Language":"1","Ds_MerchantData":"","Ds_Bizum_IdOper":"93033831588759888194372923850580115","Ds_ProcessedPayMethod":"68","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"Operacion realizada correctamente"}</details>
			<merchantTransactionId>20546099</merchantTransactionId>
			<message>Operacion realizada correctamente</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
		<paySolTransactionId>93033831588759888194372923850580115</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>AWAITING_PAYSOL</status>
			<transactionId>646268629</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b297de10_1fb2_41cd_9f76_d3dc443620b8</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>30057</id>
		<name>Bizum</name>
		<version>3</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<message>Bizum callback response has finished successfully, for the transaction Id: 646273462</message>
	<operations>
		<operation sorted-order="1">
			<amount>1.0</amount>
			<currency>EUR</currency>
		<details>{"Ds_Date":"04%2F03%2F2024","Ds_Hour":"13%3A31","Ds_SecurePayment":"1","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"Operacion realizada correctamente","Ds_Amount":"100","Ds_Currency":"978","Ds_Order":"20546099","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"312408","Ds_Bizum_CuentaTruncada":"ES72XXXXXXXXXXXXXXXX3604","Ds_Bizum_MobileNumber":"+34700000000","Ds_Bizum_IdOper":"93066994374227726480093163650083665","Ds_ProcessedPayMethod":"68"}</details>
			<merchantTransactionId>20546099</merchantTransactionId>
			<message>Auth Code : 312408 - Transaccion autorizada para pagos y preautorizaciones</message>
			<operationType>DEBIT</operationType>
			<paymentSolution>bizum</paymentSolution>
			<status>SUCCESS</status>
			<transactionId>646273462</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>2723ebd9_2d0b_4f90_a4f5_b2fd7e760edf</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<name>Bizum</name>
		<version>3</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <details>{"Ds_RtpStatus":"KO","Ds_RtpResponse":"BIZ00009","Ds_RtpDescription":"Ordenante no encontrado","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"00000001","Ds_Currency":"978","Ds_Amount":"500"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Bizum RTP CHECK result : KO</message>
      <operationType>DEBIT</operationType>
      <optionalTransactionParams/>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentDetails>
        <extraDetails/>
      </paymentDetails>
      <paymentSolution>bizum</paymentSolution>
      <status>ERROR</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>3100</code>
        <message>Response code not set</message>
        <uuid>4a5d48db_bbbe_4b03_96f2_41ff93744ba6</uuid>
      </respCode>
    </operation>
    <operation sorted-order="2">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7740186</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>b3ca7ba7_96c6_4bd3_bbf8_056ab697ab08</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>PENDING</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>26</version>
  </workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"24%2F11%2F2023","Ds_Hour":"13%3A10","Ds_SecurePayment":"1","Ds_Amount":"500","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11949962139757716477478348779539678","Ds_ProcessedPayMethod":"68","Ds_Control_1700827811045":"1700827811045"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>SUCCESS</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>c1bcd860_7bac_4bd8_914b_f6b318f00655</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

Note: In RTP operations, the authentication request in the customer’s bank application is only received in the production environment. In the staging environment, it is simulated with a 5-second pause, after which the transaction is authorized.

Two-step payment – without customer’s phone number

Authentication + authorization and capture is a 2-phase payment method. The merchant must authorize and capture the import once the customer has authenticated the transaction.

Pre-authentication has a maximum time of 30 days, after which authenticated operations cannot be authorized. The merchant will not receive the funds into your account until it is confirmed. Additionally, authentication does not block the import of the customer’s account, so funds for subsequent authorization and capture are not guaranteed.

Pre-authorizations, if the transaction is authenticated but not authorized, will show a “PENDING_CONFIRMATION” status. You can manually capture these transactions in the Addon Payments BackOffice Portal or with an H2H request to capture the amount.

If you do not know the customer’s phone number, you cannot include it in the request. It will not be possible to check if the client has RTP activated and the transaction will be made by redirection.

In a first notification you will receive the URL to which you must redirect the client to complete the operation in the “redirectionResponse” field. On the part of the merchant, you must wait until you receive a second notification with the result of the transaction.

Below is a summary of the transaction flow:

  1. You launch a request without the customer’s phone number and obtain the redirection URL.
  2. You receive a first notification informing you of the Bizum URL to which you must redirect the client to complete the transaction.
  3. You receive a second notification informing you of the status of the transaction. If the transaction was successful, in this case the status will be “PENDING_CONFIRMATION”.
  4. You capture the transaction amount through the BackOffice portal or an H2H request.

Request

These are some examples of pre-authorization requests through Bizum without the cutomer’s phone number using Hosted . Remember that the chain request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency
=EUR&country=ES&customerId=000001&autoCapture=false&statusURL
=https://micomercio.com/recepcion_notificacion
.php?tipo?redireccion&successURL=https://micomercio.com/url-ok
.php&errorURL=https://micomercio.com/url-ko.php&cancelURL
=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 76XOR/DLWobB3LzAjYo9zQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="kRkl1qQfFFloe5IEma51DW8gE7LxBj1FHdSvUTwFhf3uZjpIw/Tt2cwTRPxeCitSuCnEG3o77FuI3jK95yuB6YNnbGCf6i6Q66Gkx8gdIT698uqG7+wzYSu+p35hTHSJ3nENExq+GJlnKAIUIC2V/2Z0uxI0c+BERShgeKQA/nQuJl9yXShR+miisKytyXFUG5rTuhLopwr5xw+Z5Z/WdZi9AHiJojkD6vt6mMRt9i4gmj6MQ9dqUnJV+Hs84tWJVTUtZWCjSeZeS1bps3g0DsVv7XgoeH7GMYkGlUJW2gpErRBfkHk9MvxTL0hGbZPnaxdE/jBDGAHYK0cDdtKX0X5j1KZbXvWnEmw2ntGiMRUFuChywpC1Mdht48ca4Fj9euJnFgThpBtShqKn5pB/SZMNXiAmaQh4//3jw3t8owHalsypYUGT7pLJCgMssBxbY+AO43fg1KfMeUmzqT7LLnVjUwM6MqQ0hs1M1TiyAcNl3Jjkjh05DfDMK+a2mNbalDP9YXFZWOyUJIXTciY8yBIq51g6vOLuoT/l6NC043G4WeyQfdYl9ozw8JDtMUSaxl2xoee9aqbZh9mKp64hKwt7yevAPjasxKA3EarJv//6aHjnQTuPK4TmTTIQgndkLV2sFixICgqmbaWQuLeA3EDoPQ/X/7ZjL5k69Y6sHNfHG5+zcFbcGdKURuWVVULjhUakRPA+XBF5le0O+YnE1GxRrjS1BrZlcPtqwCpX7dKCf2GLlcaAncrAr5VbKMLDFedZwtQx/EdbOX8NuLWvMVF5889fdPyCLnOWDpGaXjM="' \
--form 'integrityCheck="a00d2a830fd1b8829a96e762bf528f5fdf07a4f56f72799fe19b42c1382dca54"'

Once the POST is sent to Addon Payments, you will receive the URL where to redirect the client:

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize
?token=e285f319-3a99-4c04-a4d9-d2b4fa468144&apiVersion=5

Request parameters

The basic parameters to send a request in this case are the Required/Mandatory (R) of the required and optional data table.

Additionally, you must add the optional ones:

  • autoCapture: Set to “false”.

Response

This is an example of the notifications you receive. The first notification informs that the customer has been redirected and the second informs of the status of the transaction:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7740186</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>b3ca7ba7_96c6_4bd3_bbf8_056ab697ab08</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>PENDING</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>26</version>
  </workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"24%2F11%2F2023","Ds_Hour":"13%3A10","Ds_SecurePayment":"1","Ds_Amount":"500","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11949962139757716477478348779539678","Ds_ProcessedPayMethod":"68","Ds_Control_1700827811045":"1700827811045"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>PENDING_CONFIRMATION</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>c1bcd860_7bac_4bd8_914b_f6b318f00655</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

You can capture the amount from the Addon Payments BackOffice portal or by a H2H request.

Two-step payment – with customer’s phone number

The authentication + authorization is a two-step payment method. Add the parameter “autoCapture: false” to the request. The customer experience doesn’t change.

The merchant has 30 days to capture the pre-authorization. However, payment is not ensured after 7 days. The merchant won’t receive the funds from the pre-authorization until it is confirmed.

Pre-authorizations, if the transaction is authenticated but not authorized, will show a “Pending” status. You can manually capture these transactions in the Addon Payments BackOffice Portal or with an H2H request to capture the amount.

If you send the customer’s phone number in the request, one of two things will happen:

  • If the customer has RTP activated, they will authorize the purchase on their banking app.
  • If the customer doesn’t have RTP activated, they will automatically be redirected to a Bizum URL to authorize the transaction. 

Regardless, the request the merchant sends is the same in both cases. 

Request

These are some sample pre-authorization requests for Bizum with the phone number via Hosted. Remember, the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=4.00&currency=EUR&countryz
=ES&customerId=000001&telephone=700000000&autoCapture=false&statusURL
=https://micomercio.com/recepcion_notificacion
.php?tipo?redireccion&successURL=https://micomercio.com/url-ok.php&errorURL
=https://micomercio.com/url-ko.php&cancelURL=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.easypaymentgateway.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: hKPRwTwCpe7LlguwzTI4VA==' \
--form 'merchantId="12345"' \
--form 'encrypted="MaOk+AQO4FcjT0wFeC5TJtOsQp5YMK7BzekTCvKS3+uJGctgZzqxReV9JWunSRHBZe84Q1I3Ru3Ni68LMmdev4PXf1S5a/y9KwkjJMIe1t2xoYzd7SDplpMcoUPTq3QRKpsQvoyGAbISF2ZeeoioeYeZGMlDJvmDEsIvXchgzfGsRlByGkljxz4J1mI343WokLAXOkylrmPbutby1U1rAVkbNtdFUO5+tZwIGGPGX/jcK1fK7A4YhWU/2ErVZ8j0QMA++X+1Rm0BmiUJksXtPWDrMmrSI7qmlPKzx7KUn0M/X+dbFOpo1patwApwEe+KpaeHGlN7rGQiH42zrn+i+yaoAHoRLwvwTpxR1ohUhdUWyC3Jka2/8L9AxwHrm7DeVS2UwAWL2QzxVuX6wuy+RbABA3yZYn8REdwKR49HqrjdxIC+UNsttTwzmcbV6tu9/kwLGdZbRMILlaomYUwEjYDDg0VsKs+LLpL9VVmaJGsmS9AOu8DCC8XzvflA6W6I62sacOR/zERYUWBAVNy8jurlULeGdmMCkUONY9B6LgM9GhgbzvGpEhpmzGy/+sWgvcs9KsNd0vMElehiUzs9O/NVPkHpzEOEEZ0RH5qX3GJn8ZMmhDZ6+MBLL5ceqoP1x0PJQxAQRu0/ZzE808TjfZjlnEFcV5vk3cA9KbvTGYs/IvV+MiTvktRYZt1KuL5nE1zh82e6q0AOqdfjI/xh1BNMntnnNxfEb+JzB44MvYVkWwtU2OovLwi4qIWKojqX"' \
--form 'integrityCheck="40bfd9c4cdd89221b23cc2fea6568b6f23650964c65f75bbebe87b347a7a9231"'

After sending the POST to Addon Payments, you will receive the URL to redirect your customer: 

				
					https://checkout.stg-eu-west3.epgint.com/EPGCheckout/rest/online/detokenize?token
=ef55c255-dd53-4768-a6ee-2dc748fdb99b&apiVersion=5

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Plus, you should add the optional ones:

  • autoCapture: Set as “false”.
  • telephone: customer’s phone number (without country code).
  • awaitingURL: Waiting URL for your business where you can redirect the customer while authenticating the transaction in their bank application.
  • phoneCode: Only for non-Spanish phone numbers.

Response

The notifications you receive change depending on whether the client has RTP enabled or not.

If RTP is enabled, you will receive 2 notifications: The first one indicating that the transaction is pending authentication by the client, and the second one indicating the status of the operation. For authentications + authorizations, the status will be “PENDING_CONFIRMATION” until you authorize the amount.

If RTP is not enabled, you will receive 2 notifications: The first one with the Bizum URL where the customer will be automatically redirected to, and the second one with indicating the status of the transaction. For authentications + authorizations, the status will be “PENDING_CONFIRMATION” until you authorize the amount.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
	<message>WorkFlow has finished successfully, for transaction Id: 646268629</message>
	<operations>
		<operation sorted-order="1">
			<amount>1.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_RtpStatus":"OK","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"Operacion realizada correctamente","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"20546099","Ds_Currency":"978","Ds_Amount":"100"}</details>
			<merchantTransactionId>20546099</merchantTransactionId>
			<message>Bizum RTP CHECK result : OK</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>20546099</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>COMPLETED</status>
			<transactionId>646268629</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>8ff71c04_63a7_4adb_a042_7bf4fa4a77cc</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>1.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_Amount":"100","Ds_Currency":"978","Ds_Order":"20546099","Ds_MerchantCode":"008043853","Ds_Terminal":"50","Ds_Response":"9998","Ds_AuthorisationCode":"","Ds_TransactionType":"0","Ds_Language":"1","Ds_MerchantData":"","Ds_Bizum_IdOper":"93033831588759888194372923850580115","Ds_ProcessedPayMethod":"68","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"Operacion realizada correctamente"}</details>
			<merchantTransactionId>20546099</merchantTransactionId>
			<message>Operacion realizada correctamente</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
		<paySolTransactionId>93033831588759888194372923850580115</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>AWAITING_PAYSOL</status>
			<transactionId>646268629</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b297de10_1fb2_41cd_9f76_d3dc443620b8</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>30057</id>
		<name>Bizum</name>
		<version>3</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<message>Bizum callback response has finished successfully, for the transaction Id: 7854833</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.0</amount>
			<currency>EUR</currency>
			<details>{"Ds_Date":"04%2F03%2F2024","Ds_Hour":"17%3A52","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"61659767","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"055219","Ds_Bizum_IdOper":"12824309843264433334493184357110832","Ds_ProcessedPayMethod":"68","Ds_Control_1709571139062":"1709571139062"}</details>
			<merchantTransactionId>61659767</merchantTransactionId>
			<message>Auth Code : 055219 - Transaccion autorizada para pagos y preautorizaciones</message>
			<operationType>DEBIT</operationType>
			<paymentSolution>bizum</paymentSolution>
			<status>PENDING_CONFIRMATION</status>
			<transactionId>7854833</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b0f08af9_8712_4079_bb1f_be0531233f01</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>PENDING_CONFIRMATION</status>
	<workFlowResponse>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <details>{"Ds_RtpStatus":"KO","Ds_RtpResponse":"BIZ00009","Ds_RtpDescription":"Ordenante no encontrado","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"00000001","Ds_Currency":"978","Ds_Amount":"500"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Bizum RTP CHECK result : KO</message>
      <operationType>DEBIT</operationType>
      <optionalTransactionParams/>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentDetails>
        <extraDetails/>
      </paymentDetails>
      <paymentSolution>bizum</paymentSolution>
      <status>ERROR</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>3100</code>
        <message>Response code not set</message>
        <uuid>4a5d48db_bbbe_4b03_96f2_41ff93744ba6</uuid>
      </respCode>
    </operation>
    <operation sorted-order="2">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7740186</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>b3ca7ba7_96c6_4bd3_bbf8_056ab697ab08</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>PENDING</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>26</version>
  </workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"24%2F11%2F2023","Ds_Hour":"13%3A10","Ds_SecurePayment":"1","Ds_Amount":"500","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11949962139757716477478348779539678","Ds_ProcessedPayMethod":"68","Ds_Control_1700827811045":"1700827811045"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>PENDING_CONFIRMATION</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>c1bcd860_7bac_4bd8_914b_f6b318f00655</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

Note: In RTP operations, the authentication request in the customer’s bank application is only received in the production environment. In the testing environment (staging), it is simulated with a pause of 5 seconds, after which the operation is authorized.

You can capture or release the amount from the Addon Payments BackOffice Portal or through an H2H request for the amount.

Host2Host integration

With Addon Payments you can integrate the Bizum payment solution into Host2Host integrations. This can be done via RTP (the customer authorizes from their banking app if they have this option activated) or by redirect to a Bizum URL.

Required and optional data Host2Host

These are the required (R) and optional (O) parameters for a Bizum transaction via Host2Host:

FieldFormatTypeDescriptionExample
merchantIdWhole number
4~7 digits		RYour merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments14983
merchantTransactionIdAlphanumeric
Max 12 characters
Min 4 characters
Does not support special characters		RThis is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order.order91684
amountNumerical with decimalsRAmount of the transaction. If the amount has decimals, the separator is a dot (.). The separator cannot be included in the thousands.127.5
currencyAlphabetical
3 characters
ISO-4217.3		RCurrency of the transactionEUR
countryAlphabetical
3 characters
ISO 4217.3		RCountry from which the transaction is sentES
customerIdAlphanumeric
Max 80 characters		RCustomer ID in your e-commerce platform.A34623
paymentSolutionAlphanumeric
Max 45 characters		RName of the payment solution to process the transaction. bizum
statusURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your e-commerce platform where AP will send the notification with the status of the transaction. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/status
successURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is authorized. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/success
errorURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is declined. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/error
cancelURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is cancelled during the payment process. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/cancel
awaitingURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		R (for clients with RTP)URL of your platform to which the customer is redirected if the transaction is via RTP and the customer has to authenticate their transaction in the bank application. If it is sent in the request, it will have priority over the one configured in the Addon Payments BackOffice Portal. If not sent in the request, the client will be redirected to the URL configured in the management pack.https://www.example.com/awaiting
telephoneAlphanumeric
Max 45 characters		OPhone number. No code.700000000
phoneCodeValid country codeOCountry code for the customer’s phone number. Only necessary for non-Spanish phone numbers.+33
autoCaptureBooleanOEstablishes whether the transaction is an authorization or pre-authorization. For the latter, the merchant must capture or release afterwards.True

Authorization – without customer’s phone number

If you do not know the customer’s phone number, you cannot include it in the request. It will not be possible to check if the client has RTP activated and the transaction will be made by redirection.

In a first notification you will receive in the “redirectionResponse” field the URL to which you must redirect the client to complete the operation. On the part of the merchant, you must wait until you receive a second notification with the result of the transaction.

Below is a summary of the transaction flow:

  1. You launch a request without the customer number.
  2. You receive a first notification informing you of the Bizum URL to which you must redirect the customer to complete the transaction.
  3. You receive a second notification informing you of the status of the transaction.

Request

These are some sample payment requests for Bizum without the phone number via Host2Host. Remember, the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=4.00&currency=EUR&country
=ES&customerId=000001&paymentSolution=bizum&statusURL=https://micomercio
.com/recepcion_notificacion.php&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.easypaymentgateway.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: TQ+v6BeLNBg8JphsymZmvg==' \
--form 'merchantId="12345"' \
--form 'encrypted="HjauGEYGslwi3uJNLBV+dGHjkUO+f9xe0EmV2Mole/xx7f86yA3xXR7o//hJ6FCj4OsjiY2zqLm3PSYgRiYtkaUT/EN3Rl4Yrv/Rv652pDt3ykSXIMpBekSXvbMlf4ANw3u0OHtthDFx3UXnSxsKAEEUWixFVZ+CI817XHJbkTt0AX80fpAxVNEu3rpKnw/5ueqht8G9uPgYucDh35oIJIIUeRNQBND7wcWkJeLRLHhRjrIwAPlo7qIw7Po7n4vOCx6CaGubAFn1ysacbLh1ww7rtiM/oyNvgwuIHiQ7S4p7c0/UAqw+LYMY4nso7/SeRssniKEUON6EtbIiym3KEMIoUxsHtDR+ncldZKltNBMOO95TYJO2uo89OD3JxSbU6UKczFL/bgVkARgR0Zaj1NJu9zWCcCd3TsjhY/efYSgMEzmwxfJklp++dU5Qn3t85i+HSs/WNF8/mHCQz21TpRDC//4+15eLzmyM7rHWB56GGh9BSeTngFcT/i2ggN5ZtUYF21FxoIn2bkcfhR1P/+sa/OdWCinz7faDCfHwUxc+72obyn1/zMbCPapWv05Ti2/F/xQ2+ynT4EwbO6fa4G7W8ASV31l4vId9FBC2OvPI5kpLg6pM0INzbWl571xRh6koGX+9fWHl50HO0KLTIeSYDSDxghIOTBNEx9eQAy6fvZko+W43OLXkA8uoK4IdO8Ir2TBzvG7ETdPJSdcioo44MAIpTbqqN3k/rNaSm8g="' \
--form 'integrityCheck="549a706477ff8b46a6b3b783c1959001e1500ce20d93b8c4dcfe70e34d7cf1c8"'

Once the POST is sent to Addon Payments, you will receive a redirect URL in a first response in the field “redirectionResponse”:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7732053</message>
  <operations>
    <operation sorted-order="1">
      <amount>4.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7732053</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7732053</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>cc9126f1_506e_4cfd_b9f8_08c38ae7ac4e</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>16</version>
  </workFlowResponse>
</response>

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Response

Once you have redirected the customer to the URL in the “redirectionResponse” field of the previous notification and the customer has completed the payment, you will receive the final response with the transaction status: 

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7732338</message>
  <operations>
    <operation sorted-order="1">
      <amount>4.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"17%2F11%2F2023","Ds_Hour":"16%3A43","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11890769189622827914078544055875742","Ds_ProcessedPayMethod":"68","Ds_Control_1700235810623":"1700235810623"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>SUCCESS</status>
      <transactionId>7732338</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>1561337c_37cd_455a_9699_f8f697e260b0</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

Authorization – with customer’s phone number

If you send the customer’s phone number in the request, one of two things will happen:

  • If the customer has RTP activated, they will authorize the purchase on their banking app.
  • If the customer doesn’t have RTP activated, they must be redirected to a Bizum URL to authorize the transaction. 

Regardless, the request the merchant sends is the same in both cases. 

Request

These are some sample payment requests for Bizum with the phone number via Host2Host. Remember, the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=4.00&currency=EUR&country
=ES&customerId=000001&paymentSolution=bizum&telephone=700000000&statusURL
=https://micomercio.com/recepcion_notificacion
.php&successURL=https://micomercio.com/url-ok.php&errorURL
=https://micomercio.com/url-ko.php&cancelURL=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.easypaymentgateway.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 9TGtX6TDQTiit7gOEfQNcw==' \
--form 'merchantId="12345"' \
--form 'encrypted="75vifOSdutnXj5OTtZRCtc2JMYtx05gc+KScBaPMNYYHP7d2WrDj4XrLWPeYxPIo7a03bVv8t0wTOzIOACVAWyzsJMyMNmaqmOVNQOL+wWbTC20/d+ERdl/mTabbkndBooqmAwSt7mgQoPoFfSfCBPpnWthN0+6GDWwPNx58ZUJDidkkB+WsqXHtcsZ3LSO7dMx+yLNZtCKttCJpSFDjKIM+br0Z0qNrcuw4vdJlgreIbr1opVsNxAYpwM2+ow8/d1YzOhWkSqVrx1E6nxscEUPee/Hfld0VyAZiRUWph9tJsADtw28EV66SXmKF6QUnaVCCzTjU8Agc+1TQAZqH13IiBjurC04dxHo9USdpbpqOwVpj4Kp6t1btScl1+bZBj1xMjupiqdEH4oWqbaFiCjgE/3/XHACsGoUf3QYTA2a7p/bAC+Enqvo8l01Fz68FhAHqK49fOovi1d4rVO/3QsoJzn6ePAKkvLAL0Hkdt+LQZUTCco/+lMoyXWG0txxRPtOjMSsbAs7gKO8gDtHgt8tt1Dd2aAVSmGZqnF6wHCqBeVEgx5K6WpKzDePcrqGLDvtgjgozF2sFEaejK0KBTWKn6O/2snJ9wZWIAGmdT6JiREV+5shaeSpP5X9Xs7ZKlUd0E69YihHVvq9Cny+KwslrUO5F6It1VSbEFBX2d3q/b8KdyPcBq6AR20W0w8ohfXeeQMOMDLBz3LaIiwQ9lJVal+/keOUvhjELpknk6oEpSVP8me7vZQF68DPG3Za1uQ00Pdanyj8SD3dV+LfaVw=="' \
--form 'integrityCheck="5f0b6ba4898696647a39cb3d88db8a10af118b532a5d5d076003c8ef5f87ad1c"'

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Plus, you should add the optional ones:

  • telephone: customer’s phone number (without country code).
  • phoneCode: Only for non-Spanish phone numbers.

Response

The notifications you receive depend on whether the customer has RTP activated.

If they have it activated, you will receive 2 notifications: The first one indicating that the transaction is pending authentication by the customer, and the second one indicating the status (success, cancelled, etc.) of the transaction.

If the customer has RTP enabled, we recommend that when the merchant receives the first notification, add a warning so that the customer knows that he has to authenticate the transaction in his bank application. In the image you can see an example that you can adapt to your merchant.

If they don’t have it activated, you will receive two notifications: the first with a URL where you must redirect the customer and the second with the transaction status. 

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
	<message>WorkFlow has finished successfully, for transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_RtpStatus":"OK","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"42252710","Ds_Currency":"978","Ds_Amount":"400"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Bizum RTP CHECK result : OK</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>42252710</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>COMPLETED</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>4a2d854d_e7d0_4856_911f_f77f04c8554f</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>4.00</amount>
			<currency>EUR</currency>
		<details>{"Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"50","Ds_Response":"9998","Ds_AuthorisationCode":"","Ds_TransactionType":"0","Ds_Language":"1","Ds_MerchantData":"","Ds_Bizum_IdOper":"12841438308837499828322983974007788","Ds_ProcessedPayMethod":"68","Ds_Control_1709742417045":"1709742417045","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>SIS-T Operacion realizada correctamente</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>12841438308837499828322983974007788</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>AWAITING_PAYSOL</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>f255ba0c_77d7_4e35_abe2_c7c5fbb030fa</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>51606</id>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<message>Bizum callback response has finished successfully, for the transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.0</amount>
			<currency>EUR</currency>
			<details>{"Ds_Date":"04%2F03%2F2024","Ds_Hour":"17%3A52","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"055219","Ds_Bizum_IdOper":"12824309843264433334493184357110832","Ds_ProcessedPayMethod":"68","Ds_Control_1709571139062":"1709571139062"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Auth Code : 055219 - Transaccion autorizada para pagos y preautorizaciones</message>
			<operationType>DEBIT</operationType>
			<paymentSolution>bizum</paymentSolution>
			<status>SUCCESS</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b0f08af9_8712_4079_bb1f_be0531233f01</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
  <message>WorkFlow has finished successfully, for transaction Id: 7732326</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <details>{"Ds_RtpStatus":"KO","Ds_RtpResponse":"BIZ00009","Ds_RtpDescription":"Ordenante no encontrado","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"00000001","Ds_Currency":"978","Ds_Amount":"500"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Bizum RTP CHECK result : KO</message>
      <operationType>DEBIT</operationType>
      <optionalTransactionParams/>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentDetails>
        <extraDetails/>
      </paymentDetails>
      <paymentSolution>bizum</paymentSolution>
      <status>ERROR</status>
      <transactionId>7732326</transactionId>
      <respCode>
        <code>3100</code>
        <message>Response code not set</message>
        <uuid>01c4d1de_b7ec_45f8_a425_0d6ebb4a63e3</uuid>
      </respCode>
    </operation>
    <operation sorted-order="2">
      <amount>5.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7732326</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7732326</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>f5469c6b_fae9_40b7_a513_0bd03726041c</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>16</version>
  </workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7732326</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"17%2F11%2F2023","Ds_Hour":"16%3A29","Ds_SecurePayment":"1","Ds_Amount":"500","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11890682709608412369688904194014401","Ds_ProcessedPayMethod":"68","Ds_Control_1700234947629":"1700234947629"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>SUCCESS</status>
      <transactionId>7732326</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>461218f4_3c18_4dbb_98bf_df7db348d863</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

Note: In RTP operations, the authentication request in the customer’s bank application is only received in the production environment. In the testing environment (staging), it is simulated with a pause of 5 seconds, after which the operation is authorized.

Pre-authorization – without customer’s phone number

The pre-authorization is a two-step payment method. Add the parameter “autoCapture: false” to the request. The customer experience doesn’t change.

 The merchant has 30 days to confirm or decline the pre-authorization. However, payment is not ensured after 7 days. The merchant won’t receive the funds from the pre-authorization until it is confirmed.

Pre-authorizations, if the transaction is authorized, will show a “Pending” status. You can manually capture these transactions in the Addon Payments BackOffice Portal or with an H2H request to capture the amount.

In this case, you can’t send the phone number in the request. So, you will receive a notification with a URL to redirect the customer (redirectionResponse). Once the operation is complete, you will receive another notification with the transaction status.  

If you do not know the customer’s phone number, you cannot include it in the request. It will not be possible to check if the client has RTP activated and the transaction will be made by redirection.

In a first notification you will receive the URL to which you must redirect the client to complete the operation in the “redirectionResponse” field. On the part of the merchant, you must wait until you receive a second notification with the result of the transaction.

Below is a summary of the transaction flow:

  1. You launch a request without the customer’s phone number.
  2. You receive a first notification informing you of the Bizum URL to which you must redirect the client to complete the transaction.
  3. You receive a second notification informing you of the status of the transaction. If it went well, in this case the status will be “PENDING_CONFIRMATION”.
  4. You capture or cancel the transaction amount using the BackOffice portal or an H2H request.

Request

These are some sample pre-authorization requests for Bizum without the phone number via Host2Host. Remember, the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&customerId=000001&paymentSolution=bizum&autoCapture=false&statusURL
=https://micomercio.com/recepcion_notificacion
.php&successURL=https://micomercio.com/url-ok.php&errorURL
=https://micomercio.com/url-ko.php&cancelURL=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 76XOR/DLWobB3LzAjYo9zQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="kRkl1qQfFFloe5IEma51DW8gE7LxBj1FHdSvUTwFhf3uZjpIw/Tt2cwTRPxeCitSuCnEG3o77FuI3jK95yuB6YNnbGCf6i6Q66Gkx8gdIT698uqG7+wzYSu+p35hTHSJ3nENExq+GJlnKAIUIC2V/2Z0uxI0c+BERShgeKQA/nQuJl9yXShR+miisKytyXFUG5rTuhLopwr5xw+Z5Z/WdZi9AHiJojkD6vt6mMRt9i4gmj6MQ9dqUnJV+Hs84tWJVTUtZWCjSeZeS1bps3g0DsVv7XgoeH7GMYkGlUJW2gpErRBfkHk9MvxTL0hGbZPnaxdE/jBDGAHYK0cDdtKX0X5j1KZbXvWnEmw2ntGiMRUFuChywpC1Mdht48ca4Fj9euJnFgThpBtShqKn5pB/SZMNXiAmaQh4//3jw3t8owHalsypYUGT7pLJCgMssBxbY+AO43fg1KfMeUmzqT7LLnVjUwM6MqQ0hs1M1TiyAcNl3Jjkjh05DfDMK+a2mNbalDP9YXFZWOyUJIXTciY8yBIq51g6vOLuoT/l6NC043G4WeyQfdYl9ozw8JDtMUSaxl2xoee9aqbZh9mKp64hKwt7yevAPjasxKA3EarJv//6aHjnQTuPK4TmTTIQgndkLV2sFixICgqmbaWQuLeA3EDoPQ/X/7ZjL5k69Y6sHNfHG5+zcFbcGdKURuWVVULjhUakRPA+XBF5le0O+YnE1GxRrjS1BrZlcPtqwCpX7dKCf2GLlcaAncrAr5VbKMLDFedZwtQx/EdbOX8NuLWvMVF5889fdPyCLnOWDpGaXjM="' \
--form 'integrityCheck="a00d2a830fd1b8829a96e762bf528f5fdf07a4f56f72799fe19b42c1382dca54"'

Once the POST is sent to Addon Payments, you will receive a redirect URL in a first response in the field “redirectionResponse”:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7735944</message>
  <operations>
    <operation sorted-order="1">
      <amount>10.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7735944</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7735944</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>0536c1aa_486c_43e3_b153_1d6fd08c0be6</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>16</version>
  </workFlowResponse>
</response>

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Plus, you should add the optional ones:

  • autoCapture: Set as “false”. 

Response

When the customer completes the payment you receive a response with the status of the transaction. The transaction will remain pending confirmation until you capture the amount.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"24%2F11%2F2023","Ds_Hour":"13%3A10","Ds_SecurePayment":"1","Ds_Amount":"500","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11949962139757716477478348779539678","Ds_ProcessedPayMethod":"68","Ds_Control_1700827811045":"1700827811045"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>PENDING_CONFIRMATION</status>
      <transactionId>7735944</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>c1bcd860_7bac_4bd8_914b_f6b318f00655</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

You can capture or release the amount from the Addon Payments BackOffice Portal or through an H2H request for the amount.

Two-step payment – with customer’s phone number

Authentication + authorization and capture is a 2-phase payment method. The business must authorize and capture the amount once the customer has authenticated the transaction.

Pre-authentications have a maximum time of 30 days, after which authenticated operations cannot be authorized. The merchant will not receive the funds in their account until it is confirmed. Additionally, authentication does not lock the amount in the customer’s account, so funds for subsequent authorization and capture are not guaranteed.

Pre-authorizations, if the transaction is authorized, will show a “PENDING_CONFIRMATION” status. You can manually capture these transactions in the Addon Payments BackOffice Portal or with an H2H request to capture the amount.

If you send the customer’s phone number in the request, one of two things will happen:

  • If the customer has RTP activated, they will authorize the purchase on their banking app.
  • If the customer doesn’t have RTP activated, they will automatically be redirected to a Bizum URL to authorize the transaction. 

Regardless, the request the merchant sends is the same in both cases. 

Request

These are some sample pre-authorization requests for Bizum with the phone number via Host2Host. Remember, the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&customerId=000001&paymentSolution=bizum&telephone=700000000&autoCapture
=false&statusURL=https://micomercio.com/recepcion_notificacion
.php&successURL=https://micomercio.com/url-ok.php&errorURL
=https://micomercio.com/url-ko.php&cancelURL=https://micomercio.com/url-cancelacion.php
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 76XOR/DLWobB3LzAjYo9zQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="kRkl1qQfFFloe5IEma51DW8gE7LxBj1FHdSvUTwFhf3uZjpIw/Tt2cwTRPxeCitSuCnEG3o77FuI3jK95yuB6YNnbGCf6i6Q66Gkx8gdIT698uqG7+wzYSu+p35hTHSJ3nENExq+GJlnKAIUIC2V/2Z0uxI0c+BERShgeKQA/nQuJl9yXShR+miisKytyXFUG5rTuhLopwr5xw+Z5Z/WdZi9AHiJojkD6vt6mMRt9i4gmj6MQ9dqUnJV+Hs84tWJVTUtZWCjSeZeS1bps3g0DsVv7XgoeH7GMYkGlUJW2gpErRBfkHk9MvxTL0hGbZPnaxdE/jBDGAHYK0cDdtKX0X5j1KZbXvWnEmw2ntGiMRUFuChywpC1Mdht48ca4Fj9euJnFgThpBtShqKn5pB/SZMNXiAmaQh4//3jw3t8owHalsypYUGT7pLJCgMssBxbY+AO43fg1KfMeUmzqT7LLnVjUwM6MqQ0hs1M1TiyAcNl3Jjkjh05DfDMK+a2mNbalDP9YXFZWOyUJIXTciY8yBIq51g6vOLuoT/l6NC043G4WeyQfdYl9ozw8JDtMUSaxl2xoee9aqbZh9mKp64hKwt7yevAPjasxKA3EarJv//6aHjnQTuPK4TmTTIQgndkLV2sFixICgqmbaWQuLeA3EDoPQ/X/7ZjL5k69Y6sHNfHG5+zcFbcGdKURuWVVULjhUakRPA+XBF5le0O+YnE1GxRrjS1BrZlcPtqwCpX7dKCf2GLlcaAncrAr5VbKMLDFedZwtQx/EdbOX8NuLWvMVF5889fdPyCLnOWDpGaXjM="' \
--form 'integrityCheck="a00d2a830fd1b8829a96e762bf528f5fdf07a4f56f72799fe19b42c1382dca54"'

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Plus, you should add the optional ones:

  • autoCapture: Set as “false”.
  • telephone: customer’s phone number (without country code).
  • phoneCode: Only for non-Spanish phone numbers.

Response

The notifications you receive change depending on whether the client has RTP activated or not.

If you have RTP activated, you will receive 2 notifications: The first indicating that the transaction is pending authentication by the customer, and the second indicating the status of the operation. For authentications + authorizations, the status will be “PENDING_CONFIRMATION” until you authorize the amount.

If you do not have RTP activated, you will receive 2 notifications: The first with the Bizum URL to which the customer will be automatically redirected, and the second indicating the status of the transaction. For authentications + authorizations, the status will be “PENDING_CONFIRMATION” until you authorize the amount.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
	<message>WorkFlow has finished successfully, for transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_RtpStatus":"OK","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"42252710","Ds_Currency":"978","Ds_Amount":"400"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Bizum RTP CHECK result : OK</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>42252710</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>COMPLETED</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>4a2d854d_e7d0_4856_911f_f77f04c8554f</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>4.00</amount>
			<currency>EUR</currency>
		<details>{"Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"50","Ds_Response":"9998","Ds_AuthorisationCode":"","Ds_TransactionType":"7","Ds_Language":"1","Ds_MerchantData":"","Ds_Bizum_IdOper":"12841438308837499828322983974007788","Ds_ProcessedPayMethod":"68","Ds_Control_1709742417045":"1709742417045","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>SIS-T Operacion realizada correctamente</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>12841438308837499828322983974007788</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>AWAITING_PAYSOL</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>f255ba0c_77d7_4e35_abe2_c7c5fbb030fa</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>51606</id>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<message>Bizum callback response has finished successfully, for the transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.0</amount>
			<currency>EUR</currency>
			<details>{"Ds_Date":"04%2F03%2F2024","Ds_Hour":"17%3A52","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"055219","Ds_Bizum_IdOper":"12824309843264433334493184357110832","Ds_ProcessedPayMethod":"68","Ds_Control_1709571139062":"1709571139062"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Auth Code : 055219 - Transaccion autorizada para pagos y preautorizaciones</message>
			<operationType>DEBIT</operationType>
			<paymentSolution>bizum</paymentSolution>
			<status>PENDING_CONFIRMATION</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b0f08af9_8712_4079_bb1f_be0531233f01</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>PENDING_CONFIRMATION</status>
	<workFlowResponse>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
  <message>WorkFlow has finished successfully, for transaction Id: 7735875</message>
  <operations>
    <operation sorted-order="1">
      <amount>10.00</amount>
      <currency>EUR</currency>
      <details>{"Ds_RtpStatus":"KO","Ds_RtpResponse":"BIZ00009","Ds_RtpDescription":"Ordenante no encontrado","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"00000001","Ds_Currency":"978","Ds_Amount":"1000"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Bizum RTP CHECK result : KO</message>
      <operationType>DEBIT</operationType>
      <optionalTransactionParams/>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentDetails>
        <extraDetails/>
      </paymentDetails>
      <paymentSolution>bizum</paymentSolution>
      <status>ERROR</status>
      <transactionId>7735875</transactionId>
      <respCode>
        <code>3100</code>
        <message>Response code not set</message>
        <uuid>30d01ef5_0151_4133_8f60_abbd447602d6</uuid>
      </respCode>
    </operation>
    <operation sorted-order="2">
      <amount>10.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7735875</redirectionResponse>
      <status>PENDING</status>
      <transactionId>7735875</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>229fcf71_ddaa_4481_84d0_62e956164a94</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>16</version>
  </workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<message>Bizum callback response has finished successfully, for the transaction Id: 7735875</message>
	<operations>
		<operation sorted-order="1">
			<amount>10</amount>
			<currency>EUR</currency>
			<details>{"Ds_Date":"04%2F03%2F2024","Ds_Hour":"17%3A52","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"055219","Ds_Bizum_IdOper":"12824309843264433334493184357110832","Ds_ProcessedPayMethod":"68","Ds_Control_1709571139062":"1709571139062"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Auth Code : 055219 - Transaccion autorizada para pagos y preautorizaciones</message>
			<operationType>DEBIT</operationType>
			<paymentSolution>bizum</paymentSolution>
			<status>PENDING_CONFIRMATION</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b0f08af9_8712_4079_bb1f_be0531233f01</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>PENDING_CONFIRMATION</status>
	<workFlowResponse>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>

Note: In RTP operations, the authentication request in the customer’s bank application is only received in the production environment. In the testing environment (staging), it is simulated with a pause of 5 seconds, after which the operation is authorized.

You can capture or release the amount from the Addon Payments BackOffice Portal or through an H2H request for the amount.

Refunds Bizum – H2H

You can refund Bizum transactions as long as:

  • The transaction is authorized and captured (status “success”).

You have two ways to process refunds:

  1. Through the BackOffice Portal, as you can see in the section on Secondary operations.
  2. By sending a refund request, as you can see below.

Refund by request

Send a request to this endpoint:

EntornoURL
Staginghttps://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate
Productionhttps://checkout.addonpayments.com/EPGCheckout/rest/online/rebate

These are the required (R) and optional (O) parameters to make a return in Bizum:

Important: In “paymentSolution” you must indicate “bizum”.

FieldFormatTypeDescriptionExample
merchantIdWhole number
4~7 digits		RYour merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments14983
transactionIdWhole number
max 100 digits		RID for the original transaction the secondary operation applies to, such as capture, release or refund.76543210
paymentSolutionAlphanumeric
max 45 characters		RName of the payment solution that processed the original transaction. Given in the response for the original transaction.bizum
merchantTransactionIdAlphanumeric
Max 12 characters
Min 4 characters
Does not support special characters		RThis is the transaction ID on your ecommerce platform.
Allows your platform to link notifications received to the customer’s order.
Each transaction must have a unique ID.		order91684
amountNumerical with decimals
0~1000000.00		OAmount of the transaction which is to be refunded. May not exceed the total amount. If the amount has decimals, the separator is a dot (.). The separator cannot be included in the thousands.2
descriptionMax 1000 characters
Page of Latin-1 codes (ISO-8859-1)		ODescription of the transaction.
Saved in the transaction details and returned in the notification.
Doesn’t affect the transaction. Helps you identify it more easily.		Refund after returning product

Request

These are some sample of total refund requests for Bizum via H2H. Remember the request string must be encrypted.

				
					merchantId=12345&merchantTransactionId=00000001&amount=4.00&paymentSolution=bizum&transactionId=7742316
				
			
				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: Z7VA6TpG9B84X9x9qqXoWQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="4xUYxJxLc/ABCyqJfwttTalkds3YeijsJe6MlTnC6mgmbm0aXKwhI7thwa70o6lLyjrUtW8fFNUWf/l3jIojR4H5nW54Pl+GxerG1/AjMFpHlacchB3+kfkZzko42dQKk7MopAALi6SAFbl1Uq//qsESz8fV07ED7IvRQwlXREZDFtxQn2m9eyPr5zrJczILhRx27p3lqFQ61Sqlq0nCN+3sgJmuPUMKRqlXhYqf+vErv+fBaZMPV/8iKgERJLpIjPn+HZSLpc+q5VBcD4b+rGAgEKNi56Ni/MPCpKVWBUv8HFb06PngrLfiXcnFTfNeegg0XPkkmuGwR1l1y/k1tv9dPrdBkSIwE2OuHYvrkrn+NAOTHBxjGR4Ap93aZEwcPX9afkHkFOMi/5e3JdoxtFvSwOCe1ScEw2vRDhonE+5lV7jwOrqSMr+tfWVGPqzrYj/DZiQwCIUQJM6g5x+ocLTAURzz4IiJ26kBlQpYVnedKEVhevNJNZ88z6m50W2THtDR70pQq6qjF37NCfOeq/UDCg0RB/MPfYUJRUIsfPk=' \
--form 'integrityCheck="1c256f5b834e5db6d5f453043a8a3830859b308f297cc2cf423064510c5c9b72"'

Response

This is the notification received to a Bizum refund. If the refund is partial, you can see the initial amount and the remaining:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <operations>
    <operation sorted-order="1">
      <amount>4.00</amount>
      <currency>EUR</currency>
      <details>{"Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"50","Ds_Response":"0900","Ds_AuthorisationCode":"000000","Ds_TransactionType":"3","Ds_SecurePayment":"1","Ds_Language":"1","Ds_MerchantData":"","Ds_Bizum_IdOper":"8926042f-51c4-47ff-8d21-4936faa7d7b","Ds_ProcessedPayMethod":"68","Ds_Control_1701173917133":"1701173917133"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Operation SUCCESS, with Authorization code : 000000</message>
      <operationType>REFUND</operationType>
      <optionalTransactionParams/>
      <originalAmount>4.0</originalAmount>
      <originalCurrency>EUR</originalCurrency>
      <originalTransactionId>7742316</originalTransactionId>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <remainingAmount>0.00</remainingAmount>
      <status>SUCCESS</status>
      <transactionId>7743183</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>5db4ea22_9694_4423_a3ce_911a269b714a</uuid>
      </respCode>
    </operation>
  </operations>
  <status>SUCCESS</status>
</response>

JavaScript integration

With Addon Payments you can integrate the Bizum payment solution into JavaScript integrations. This can be done via RTP (the customer authorizes from their banking app if they have this option activated) or by redirect to a Bizum URL.

You can choose which payment options the cashier shows: Full (all the payment solutions available) or limited (in this case to Bizum). This is established based on the function you use in rendering, as you will see below.

This is a summary of the Bizum integration using JavaScript. You can get more general information in the Complement your JavaScript integration guide:

  1. You request a unique, one-time use authToken to be able to link the ATM on your website.
  2. Your e-commerce platform links the AP cashier in a “div” element of your website using the chosen upload function (full cashier or limited cashier).
  3. AP compiles the cashier selects the “div” of your website passed as a parameter to the load function.
  4. The customer selects the Bizum payment method and presses the “Pay” button
  5. AP returns a “prepayToken” to your website, which you must capture using a javascript listener.
  6. Your e-commerce platform collects the “prepayToken” and sends a collection request to AP containing it.

Getting the authToken and rendering the cashier

The first step is to get the “authToken” so we can render the cashier. A request must be sent with at least the info shown below:

				
					{
    "merchantId":"12345",
    "merchantKey":"356a8a53-b188-404d-b6c1-5bd44f48066a",
    "productId":"123450001",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "operationType": "debit"
}
				
			
				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId":"12345",
    "merchantKey":"356a8a53-b188-404d-b6c1-5bd44f48066a",
    "productId":"123450001",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "operationType": "debit"
}'

If the request is valid, Addon Payments will return an “authToken” for you to render the cashier on the frontend of your page. If the request isn’t valid, you will get a message like you see on the second tab:

				
					{
    "authToken": "23ed4dda-79f5-4a60-bcc0-52fe2f27b26e"
}
				
			
				
					{
    "error": true,
    "errorMessage": "Invalid merchant id or merchant key",
    "errorCode": 400
}

The authorization tokens received have the following characteristics:

  • Valid for 30 minutes.
  • Can be used several times to link to the payment gateway.

Parameters of the authToken request

The type shows whether the element is Required (R) or Optional (O).

FieldFormatTypeDescriptionExample
merchantIdWhole number
4~7 digits		RYour merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments14983
merchantKeyAlphanumeric
UUID Format		RThe JavaScript password. Used to verify the request is legitimate. For the staging environment, it comes in the welcome email. For production environments, recover it from the BackOffice.67a33d37-64b9-408e-a1b7-cef28ef94970
productIdWhole number
6~11 digits		RProduct ID created on your AP merchant. You’ll find it in the welcome email.149830
currencyAlphabetical
3 characters
ISO-4217.3		RCurrency of the transactionEUR
countryAlphabetical
2 characters
ISO 3166-1 alfa-2		RCountry from which the transaction is sentES
customerIdAlphanumeric
Max 80 characters		RCustomer ID in your e-commerce platform.
– To save the customer’s card token, use the “forceTokenRequest” parameter, with value “true” to save the token and “false” not to.
– To show or hide the option to remember the customer’s card, use the “showRememberMe” parameter, with value “true” to show it and “false” to hide it.		A34623
operationTypeAlphanumeric
Max 45 characters		RShows type of operation to carry out. Valores admitidos:
– debit (default): Payment transaction. That is, cash travels from the customer’s account to the merchant.
– credit: Deposit transaction to the customer’s account. That is, cash travels from the merchant to the customer’s account. For example, in the payment of a prize. Not to be confused with returns. These have their own type of transaction.		debit
showRememberMePossible values:
– true: Displays the “Remember Me” checkbox, which the customer can select (or not) to save the card token.
– false: Does not display the “Remember Me” checkbox. The card token will only be saved if “forceTokenRequest” is set to true.		OShows or hides the “Remember Me” checkbox, allowing the customer to choose whether to save the card token.true
forceTokenRequestBoolean
– true
– false		OIndicates whether to save the customer’s card token. Use “false” if you don’t want to save the card. If this value is “true” but the customer does not check the “Remember Me” box, the token will not be saved.false

Rendering the cashier on your frontend

After you get the “authToken” you can render the cashier on your frontend. Remember, the cashier can’t be rendered on a localhost and you must authorize the domain from the Addon Payments dashboard. For more rendering options, see our JavaScript guide.

Below is a simple example showing how to render the Bizum payment method:

				
					<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>JS render cashier</title>
    <style>
        #render-cashier {
            width: 350px;
            margin-top: 100px;
            border: 1px solid #ccc;
            padding: 20px;
            text-align: center;
        }
    </style>
</head>
<body>
    <div id="render-cashier"></div>
    <script src="https://epgjs-rendercashier-stg.addonpayments.com/js/public/epgjs-4.0.0-min.js"></script>
    <script>
        var authtoken = "39c1cd83-fca9-4073-b056-7fbfe95c9e69"; // Add here your authToken
        function prePayCallback(prepayData) {
            // Show prepayToken This is just for example purposes only and should not be shown to your customer
            alert(JSON.stringify(prepayData, null, 2));
        }
        function displayingMessageOnButtonClick() {
            EPGJS_COMM.setEpgBaseUrl('https://epgjs-web-stg.addonpayments.com/');
            EPGJS.renderIntegratedCashier(authtoken, 'render-cashier', 'bizum');            
            EPGJS_COMM.setMerchantPrePayCallback(prePayCallback);
        }
        window.onload = displayingMessageOnButtonClick;
    </script>
</body>
</html>

In this example code there are 3 mandatory functions for the correct functioning of the JavaScript cashier. These are:

1.  EPGJS_COMM.setEpgBaseUrl(‘Base URL’): Sets the URL to which the form will send the customer data. It changes depending on the environment where you are operating.

2. EPGJS.renderIntegratedCashier: It is the cashier rendering function. It establishes how it will look. In this example, the cashier renders bizum only. If you want to load all the payment solutions you have available, delete ‘bizum’ from “EPGJS.renderIntegratedCashier”. It would look like this:

EPGJS.renderIntegratedCashier(authtoken, 'render-cashier');

3. EPGJS_COMM.setMerchantPrePayCallback(receive function): Sets the response’s capture, which we must have created previously.This will allow you to render the cashier in the front-end div so that the customer can proceed with the payment. When the customer proceeds with the payment button, Addon Payments will return an object with the prepayToken, allowing you to submit the payment request.

Getting the prepayToken

When the customer clicks on the Bizum payment button, Addon Payments will return a “prepayToken” you have to use to send the charge request, as you will see in the next operations. Here is an example:

"prePayToken": "8862abf9-ca5a-49da-9527-1e3163e64954"

Your platform must store this code to continue to the next step. The authorization tokens received have the following characteristics:

  • Valid for 30 minutes.
  • It can only be used to authorize payment once.

Required and optional data JS charge

These are the required (R) and optional (O) parameters for a Bizum charge via JavaScript:

FieldFormatTypeDescriptionExample
prepayTokenAlphanumeric
UUID		RIt is sent in the header of the request.
AP returns this reference after the customer enters their data in the JS payment form. It is the reference that links to the customer’s card or account data for JavaScript integration.		97fe3726-adb1-4e24-9fb8-92593a75ae74
merchantIdNumeric
4~7 dígits		RIt is the indicator of your trade on the AP platform. It is provided by Support in the welcome email, it is common for both environments14983
merchantTransactionIdAlphanumeric
Max 12 characters
Min 4 characters
Does not support special characters		RThis is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order.order91684
amountNumerical with decimalsRAmount of the transaction. If the amount has decimals, the separator is a dot (.). The separator cannot be included in the thousands.127.5
currencyAlphabetical
3 characters
ISO-4217.3		RCurrency of the transactionEUR
countryAlphabetical
3 characters
ISO 4217.3		RCountry from which the transaction is sentES
paymentSolutionAlphanumeric
Max 45 characters		RName of the payment solution to process the transaction.bizum
customerIdAlphanumeric
Max 80 characters		RCustomer ID in your e-commerce platform.A34623
statusURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your e-commerce platform where AP will send the notification with the status of the transaction. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/status
successURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is authorized. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/success
errorURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is declined. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/error
cancelURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		RURL of your platform to which the customer is redirected if the transaction is cancelled during the payment process. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.https://www.example.com/cancel
awaitingURLAlphanumeric (characters allowed in URL)
Max. 2048 characters		R (for customers with RTP)URL of your platform to which the customer is redirected if the transaction is via RTP and the customer has to authenticate their transaction in the bank application. If it is sent in the request, it will have priority over the one configured in the Addon Payments BackOffice Portal. If not sent in the request, the client will be redirected to the URL configured in the management pack.https://www.example.com/awaiting
telephoneAlphanumeric
Max 45 characters		RPhone number. No code.700000000
phoneCodeValid country codeRCountry code for the customer’s phone number. Only necessary for non-Spanish phone numbers.+33
autoCaptureBoolean
– true: Automatically capture the amount.
– false: Manual capture.		OEstablishes whether the transaction is an authorization or authentication + authorization and capture. For the latter, the merchant must capture or release afterwards.True

Charge – without customer’s phone number

If you do not know the customer’s phone number, you cannot include it in the request. It will not be possible to check if the customer has RTP activated and the transaction will be made by redirection.

In a first notification you will receive in the “redirectionResponse” field the URL to which you must redirect the customer to complete the operation. On the part of the merchant, you must wait until you receive a second notification with the result of the transaction.

Below is a summary of the transaction flow:

  1. You get the authToken and render the cashier.
  2. You get the prepayToken.
  3. You launch the charge without the customer number. (This is the point where we are)
  4. You receive a first notification informing you of the Bizum URL to which you must redirect the client to complete the transaction.
  5. You receive a second notification informing you of the status of the transaction.

Request

Once you get the authToken, render the cashier and get the prepayToken, you can send the charge request. Below is a sample request and response with the basic fields for a Bizum charge without phone number.

				
					{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "amount":"10.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "productId":"123450001",
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php"
}
				
			
				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 5b16a3a7-745a-490e-be69-4c94632e810d ' \
--data-raw '{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "amount":"10.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "productId":"123450001",
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php"
}'

After sending the charge, as you didn’t include the customer’s phone number, you will receive a first notification with the URL to redirect your customer to complete payment. This URL will come in the “redirectionResponse” field.

				
					<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<payfrex-response operation-size=\"1\">
  <message>WorkFlow has finished successfully, for transaction Id: 7748982</message>
  <operations>
    <operation sorted-order=\"1\">
      <amount>4.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <payFrexTransactionId>7748982</payFrexTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7748982</redirectionResponse>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>7b57a887_9692_4601_afa5_5484bb0fa01e</uuid>
      </respCode>
      <status>PENDING</status>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>27</version>
  </workFlowResponse>
</payfrex-response>

Charge parameters

The parameters you have to send are shown on the Charge parameters table. In this case, they are all required (R).

Response

Once the customer has completed payment, they will be redirected to the success or error URL depending on the transaction result. Additionally, the merchant statusURL will be notified of the payment result.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7748985</message>
  <operations>
    <operation sorted-order="1">
      <amount>4.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"01%2F12%2F2023","Ds_Hour":"18%3A07","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"12012235171751293542359516641966458","Ds_ProcessedPayMethod":"68","Ds_Control_1701450461429":"1701450461429"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <payFrexTransactionId>7748985</payFrexTransactionId>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>SUCCESS</status>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</payfrex-response>

Charge – with customer’s phone number

If you send the customer’s phone number in the request, one of two things will happen:

  • If the customer has RTP activated, they will authorize the purchase on their banking app.
  • If the customer doesn’t have RTP activated, they must be redirected to a Bizum URL to authorize the transaction. 

Regardless, the request the merchant sends is the same in both cases. 

Request

Once you get the authToken, render the cashier and get the prepayToken, you can send the charge request. Below is a sample request and response with the basic fields for a Bizum charge with phone number.

				
					{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "productId":"123450001",
    "amount":"4.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "phoneCode":"34",
    "telephone":"700000000",
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php"
}
				
			
				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 5b16a3a7-745a-490e-be69-4c94632e810d ' \
--data-raw '{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "productId":"123450001",
    "amount":"10.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "phoneCode":"34",
    "telephone":"700000000",
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php"
}'

Request parameters

The basic parameters for sending a request are the Required (R) parameters on the table of required and optional data. 

Plus, you should add the optional ones:

  • telephone: customer’s phone number (without country code).
  • awaitingURL: Waiting URL for your business where you can redirect the customer while authenticating the transaction in their bank application.
  • phoneCode: Only for non-Spanish phone numbers.

Response

The notifications you receive depend on whether the customer has RTP activated.

If they have RTP activated, you will receive 2 notifications: The first indicating that the transaction is pending authentication by the customer, and the second indicating the status (success, canceled, etc.) of the operation.

If they do not have RTP activated, you will receive 2 notifications: The first with the Bizum URL where you must redirect the client (“redirectionResponse” field), and the second with indicating the status of the transaction.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
	<message>WorkFlow has finished successfully, for transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_RtpStatus":"OK","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"42252710","Ds_Currency":"978","Ds_Amount":"400"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Bizum RTP CHECK result : OK</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>42252710</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>COMPLETED</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>4a2d854d_e7d0_4856_911f_f77f04c8554f</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>4.00</amount>
			<currency>EUR</currency>
		<details>{"Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"50","Ds_Response":"9998","Ds_AuthorisationCode":"","Ds_TransactionType":"0","Ds_Language":"1","Ds_MerchantData":"","Ds_Bizum_IdOper":"12841438308837499828322983974007788","Ds_ProcessedPayMethod":"68","Ds_Control_1709742417045":"1709742417045","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>SIS-T Operacion realizada correctamente</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>12841438308837499828322983974007788</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>AWAITING_PAYSOL</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>f255ba0c_77d7_4e35_abe2_c7c5fbb030fa</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>51606</id>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<message>Bizum callback response has finished successfully, for the transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.0</amount>
			<currency>EUR</currency>
			<details>{"Ds_Date":"04%2F03%2F2024","Ds_Hour":"17%3A52","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"055219","Ds_Bizum_IdOper":"12824309843264433334493184357110832","Ds_ProcessedPayMethod":"68","Ds_Control_1709571139062":"1709571139062"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Auth Code : 055219 - Transaccion autorizada para pagos y preautorizaciones</message>
			<operationType>DEBIT</operationType>
			<paymentSolution>bizum</paymentSolution>
			<status>SUCCESS</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b0f08af9_8712_4079_bb1f_be0531233f01</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<payfrex-response operation-size=\"2\">
  <message>WorkFlow has finished successfully, for transaction Id: 7748661</message>
  <operations>
    <operation sorted-order=\"1\">
      <amount>10.00</amount>
      <currency>EUR</currency>
      <details>{\"Ds_RtpStatus\":\"KO\",\"Ds_RtpResponse\":\"BIZ00009\",\"Ds_RtpDescription\":\"Ordenante no encontrado\",\"Ds_MerchantCode\":\"008043853\",\"Ds_Terminal\":\"050\",\"Ds_Order\":\"00000001\",\"Ds_Currency\":\"978\",\"Ds_Amount\":\"1000\"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Bizum RTP CHECK result : KO</message>
      <operationType>DEBIT</operationType>
      <optionalTransactionParams/>
      <payFrexTransactionId>7748661</payFrexTransactionId>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentDetails>
        <account/>
        <extraDetails/>
      </paymentDetails>
      <paymentSolution>bizum</paymentSolution>
      <respCode>
        <code>3099</code>
        <message>Unidentified error</message>
        <uuid>19dbc45c_f8ac_4d77_bc8e_4c93ad762e35</uuid>
      </respCode>
      <status>ERROR</status>
    </operation>
    <operation sorted-order=\"2\">
      <amount>10.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <payFrexTransactionId>7748661</payFrexTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7748661</redirectionResponse>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>7b57a887_9692_4601_afa5_5484bb0fa01e</uuid>
      </respCode>
      <status>PENDING</status>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>27</version>
  </workFlowResponse>
</payfrex-response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7748661</message>
  <operations>
    <operation sorted-order="1">
      <amount>10.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"01%2F12%2F2023","Ds_Hour":"13%3A28","Ds_SecurePayment":"1","Ds_Amount":"1000","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"0","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"12010557780076608916549134960116084","Ds_ProcessedPayMethod":"68","Ds_Control_1701433687000":"1701433687000"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <payFrexTransactionId>7748661</payFrexTransactionId>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>SUCCESS</status>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</payfrex-response>

Note: In RTP operations, the authentication request in the customer’s bank application is only received in the production environment. In the testing environment (staging), it is simulated with a pause of 5 seconds, after which the operation is authorized.

Two-step payment – without customer’s phone number

Authentication + authorization and capture is a 2-phase payment method. The business must authorize and capture the amount once the customer has authenticated the transaction.

Pre-authentications have a maximum time of 30 days, after which authenticated operations cannot be authorized. The merchant will not receive the funds in their account until it is confirmed. Additionally, authentication does not lock the amount in the customer’s account, so funds for subsequent authorization and capture are not guaranteed.

Pre-authorizations, if the transaction is authorized, will show a “PENDING_CONFIRMATION” status. You can manually capture these transactions in the Addon Payments BackOffice Portal or with an H2H request to capture the amount.

If you do not know the client’s phone number, you cannot include it in the request. It will not be possible to check if the client has RTP activated and the transaction will be made by redirection.

In a first notification you will receive in the “redirectionResponse” field the URL to which you must redirect the client to complete the operation. On the part of the merchant, you must wait until you receive a second notification with the result of the transaction.

Below is a summary of the transaction flow:

  1. You get the authToken and render the cashier.
  2. You get the prepayToken.
  3. You launch the charge without the customer number. (we are here)
  4. You receive a first notification informing you of the Bizum URL to which you must redirect the client to complete the transaction.
  5. You receive a second notification informing you of the status of the transaction. If the transaction was successful, in this case the status will be “PENDING_CONFIRMATION”.
  6. You capture or cancel the transaction amount using the BackOffice portal or an H2H request.

Request

Once you have obtained the authToken, rendered the cashier and obtained the prepayToken, you can launch the charge request. Below, we show you an example of a request and response with the basic fields for Bizum for a pre-authentication charge without the phone number.

				
					{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "productId":"123450001",
    "amount":"4.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "autocapture": false,
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php"
}
				
			
				
					cURL:
curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 5112faba-e392-4c39-9508-87661ce15ba5' \
--data-raw '{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "productId":"123450001",
    "amount":"10.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "autocapture": false,
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php"
}'

Once the charge has been sent, as the customer’s phone number has not been indicated, you will receive an initial notification with a URL to redirect the customer to complete the payment. This URL is in the “redirectionResponse”

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7754307</message>
  <operations>
    <operation sorted-order="1">
      <amount>4.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>73348400</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <payFrexTransactionId>7754307</payFrexTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7754307</redirectionResponse>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>9d135c37_6ff6_4a79_8611_859f01f4d746</uuid>
      </respCode>
      <status>PENDING</status>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>27</version>
  </workFlowResponse>
</payfrex-response>

Charge parameters

The parameters that must be sent are detailed in the charge parameters table. In this case, they are all required (R).

Additionally, you must add:

  • autoCapture: Set to “false”.

Response

When the customer completes the payment you receive a response with the status of the transaction. The transaction will remain pending confirmation until you capture the amount.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"24%2F11%2F2023","Ds_Hour":"13%3A10","Ds_SecurePayment":"1","Ds_Amount":"500","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11949962139757716477478348779539678","Ds_ProcessedPayMethod":"68","Ds_Control_1700827811045":"1700827811045"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>PENDING_CONFIRMATION</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>c1bcd860_7bac_4bd8_914b_f6b318f00655</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

You can capture or release the amount from the Addon Payments BackOffice Portal or through an H2H request for the amount.

Two-step payment – with customer’s phone number

Authentication + authorization and capture is a 2-phase payment method. The business must authorize and capture the amount once the customer has authenticated the transaction.

Pre-authentications have a maximum time of 30 days, after which authenticated operations cannot be authorized. The merchant will not receive the funds in their account until it is confirmed. Additionally, authentication does not lock the amount in the customer’s account, so funds for subsequent authorization and capture are not guaranteed.

In this operation, if the transaction is authenticated but not authorized, it will remain in status “PENDING_CONFIRMATION”. You can manually capture these transactions in the Addon Payments BackOffice Portal or with an H2H request to capture the amount.

If the merchant sends the customer’s phone number in the request, two things can happen:

  • If the client has RTP activated, when you send a valid request, it will be pending authentication by the client in their bank application.
  • If the customer does not have RTP enabled, the customer will be redirected to a Bizum URL automatically, where they must authenticate the transaction.

Regardless of whether the client has RTP activated or not, the request that the business must send is the same in both cases.

Request

Once you have obtained the authToken, rendered the cashier and obtained the prepayToken, you can launch the charge request. Below, we show you an example of a request and response with the basic fields for Bizum for a pre-authentication charge with the phone number.

				
					{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "productId":"123450001",
    "amount":"4.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "telephone":"700000000",
    "autocapture": false,
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php",
    "awaitingURL":"https:\/\/micomercio.com\/url-espera.php"
}

				
			
				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 5112faba-e392-4c39-9508-87661ce15ba5' \
--data-raw '{
    "merchantId":"12345",
    "merchantTransactionId":"00000001",
    "productId":"123450001",
    "amount":"4.00",
    "currency":"EUR",
    "country":"ES",
    "customerId":"000001",
    "paymentSolution":"bizum",
    "telephone":"700000000",
    "autocapture": false,
    "statusURL":"https:\/\/micomercio.com\/recepcion_notificacion.php",
    "successURL":"https:\/\/micomercio.com\/url-ok.php",
    "errorURL":"https:\/\/micomercio.com\/url-ko.php",
    "cancelURL":"https:\/\/micomercio.com\/url-cancelacion.php",
    "awaitingURL":"https:\/\/micomercio.com\/url-espera.php"
}'

Charge parameters

The parameters that must be sent are detailed in the charge parameters table. In this case, they are all required (R).

Additionally, you must add:

  • autoCapture: Set to “false”.
  • telephone: customer’s phone number (without the prefix).
  • awaitingURL: Waiting URL for your business where you can redirect the customer while authenticating the transaction in their bank application.
  • phoneCode: Prefix. Only if the phone number is not Spanish.

Response

The notifications you receive change depending on whether the customer has RTP activated or not.

If they have RTP activated, you will receive 2 notifications: The first indicating that the transaction is pending authentication by the client, and the second indicating the status of the operation. For authentications + authorizations, the status will be “PENDING_CONFIRMATION” until you authorize the amount.

If they do not have RTP activated, you will receive 2 notifications: The first with the Bizum URL to which the client will be automatically redirected, and the second indicating the status of the transaction. For authentications + authorizations, the status will be “PENDING_CONFIRMATION” until you authorize the amount.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="2">
	<message>WorkFlow has finished successfully, for transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.00</amount>
			<currency>EUR</currency>
			<details>{"Ds_RtpStatus":"OK","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"42252710","Ds_Currency":"978","Ds_Amount":"400"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Bizum RTP CHECK result : OK</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>42252710</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>COMPLETED</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>4a2d854d_e7d0_4856_911f_f77f04c8554f</uuid>
			</respCode>
		</operation>
		<operation sorted-order="2">
			<amount>4.00</amount>
			<currency>EUR</currency>
		<details>{"Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"50","Ds_Response":"9998","Ds_AuthorisationCode":"","Ds_TransactionType":"7","Ds_Language":"1","Ds_MerchantData":"","Ds_Bizum_IdOper":"12841438308837499828322983974007788","Ds_ProcessedPayMethod":"68","Ds_Control_1709742417045":"1709742417045","Ds_RtpResponse":"BIZ00000","Ds_RtpDescription":"SIS-T Operacion realizada correctamente"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>SIS-T Operacion realizada correctamente</message>
			<operationType>DEBIT</operationType>
			<optionalTransactionParams/>
			<paySolTransactionId>12841438308837499828322983974007788</paySolTransactionId>
			<paymentDetails>
				<extraDetails/>
			</paymentDetails>
			<paymentSolution>bizum</paymentSolution>
			<status>AWAITING_PAYSOL</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>f255ba0c_77d7_4e35_abe2_c7c5fbb030fa</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>SUCCESS</status>
	<workFlowResponse>
		<id>51606</id>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
	<message>Bizum callback response has finished successfully, for the transaction Id: 7857761</message>
	<operations>
		<operation sorted-order="1">
			<amount>4.0</amount>
			<currency>EUR</currency>
			<details>{"Ds_Date":"04%2F03%2F2024","Ds_Hour":"17%3A52","Ds_SecurePayment":"1","Ds_Amount":"400","Ds_Currency":"978","Ds_Order":"42252710","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"055219","Ds_Bizum_IdOper":"12824309843264433334493184357110832","Ds_ProcessedPayMethod":"68","Ds_Control_1709571139062":"1709571139062"}</details>
			<merchantTransactionId>42252710</merchantTransactionId>
			<message>Auth Code : 055219 - Transaccion autorizada para pagos y preautorizaciones</message>
			<operationType>DEBIT</operationType>
			<paymentSolution>bizum</paymentSolution>
			<status>PENDING_CONFIRMATION</status>
			<transactionId>7857761</transactionId>
			<respCode>
				<code>0000</code>
				<message>Successful</message>
				<uuid>b0f08af9_8712_4079_bb1f_be0531233f01</uuid>
			</respCode>
		</operation>
	</operations>
	<optionalTransactionParams/>
	<status>PENDING_CONFIRMATION</status>
	<workFlowResponse>
		<name>Bizum</name>
		<version>17</version>
	</workFlowResponse>
</response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="2">
  <message>WorkFlow has finished successfully, for transaction Id: 7754307</message>
  <operations>
    <operation sorted-order="1">
      <amount>10.00</amount>
      <currency>EUR</currency>
      <details>{"Ds_RtpStatus":"KO","Ds_RtpResponse":"BIZ00009","Ds_RtpDescription":"Ordenante no encontrado","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Order":"73348400","Ds_Currency":"978","Ds_Amount":"1000"}</details>
      <merchantTransactionId>73348400</merchantTransactionId>
      <message>Bizum RTP CHECK result : KO</message>
      <operationType>DEBIT</operationType>
      <optionalTransactionParams/>
      <payFrexTransactionId>7754307</payFrexTransactionId>
      <paySolTransactionId>73348400</paySolTransactionId>
      <paymentDetails>
        <account/>
        <extraDetails/>
      </paymentDetails>
      <paymentSolution>bizum</paymentSolution>
      <respCode>
        <code>3099</code>
        <message>Unidentified error</message>
        <uuid>e50bbcfb_dae6_4366_b751_9c4fc4281b08</uuid>
      </respCode>
      <status>ERROR</status>
    </operation>
    <operation sorted-order="2">
      <amount>10.00</amount>
      <currency>EUR</currency>
      <merchantTransactionId>73348400</merchantTransactionId>
      <message>Redirecting to bizum</message>
      <operationType>DEBIT</operationType>
      <payFrexTransactionId>7754307</payFrexTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <redirectionResponse>redirect:/rest/online/bizum/redirect?transactionId=7754307</redirectionResponse>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>9d135c37_6ff6_4a79_8611_859f01f4d746</uuid>
      </respCode>
      <status>PENDING</status>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
  <workFlowResponse>
    <id>51297</id>
    <name>Bizum</name>
    <version>27</version>
  </workFlowResponse>
</payfrex-response>
				
			
				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
  <message>WorkFlow has finished successfully, for transaction Id: 7740186</message>
  <operations>
    <operation sorted-order="1">
      <amount>5.0</amount>
      <currency>EUR</currency>
      <details>{"Ds_Date":"24%2F11%2F2023","Ds_Hour":"13%3A10","Ds_SecurePayment":"1","Ds_Amount":"500","Ds_Currency":"978","Ds_Order":"00000001","Ds_MerchantCode":"008043853","Ds_Terminal":"050","Ds_Response":"0000","Ds_MerchantData":"","Ds_TransactionType":"7","Ds_ConsumerLanguage":"1","Ds_AuthorisationCode":"000000","Ds_Bizum_CuentaTruncada":"ES51XXXXXXXXXXXXXXXX0001","Ds_Bizum_IdOper":"11949962139757716477478348779539678","Ds_ProcessedPayMethod":"68","Ds_Control_1700827811045":"1700827811045"}</details>
      <merchantTransactionId>00000001</merchantTransactionId>
      <message>Auth Code : 000000 - Transaccion autorizada para pagos y preautorizaciones</message>
      <operationType>DEBIT</operationType>
      <paySolTransactionId>00000001</paySolTransactionId>
      <paymentSolution>bizum</paymentSolution>
      <status>PENDING_CONFIRMATION</status>
      <transactionId>7740186</transactionId>
      <respCode>
        <code>0000</code>
        <message>Successful</message>
        <uuid>c1bcd860_7bac_4bd8_914b_f6b318f00655</uuid>
      </respCode>
    </operation>
  </operations>
  <optionalTransactionParams/>
  <status>SUCCESS</status>
</response>

Note: In RTP operations, the authentication request in the customer’s bank application is only received in the production environment. In the testing environment (staging), it is simulated with a pause of 5 seconds, after which the operation is authorized.

You can capture or release the amount from the Addon Payments BackOffice Portal or through an H2H request for the amount.

Error codes

These are the error codes you may receive in Bizum notifications. You’ll find them in the lines “code”, “paymentCode”, “paymentMessage”.

< code >Addon Payments CodeAddon Payments Message
Payment Solution Code		 Payment Solution Message
1501Functionality not available with this accountBIZ00202Functionality not yet implemented.
1501Functionality not available with this accountSIS0028Error Merchant / terminal is de-registered
1502Insufficient funds9677Bizum. Insufficient funds available.
1502Insufficient fundsSIS0677Bizum. Insufficient funds available.
1507Unknown error by the Payment Solution.SIS0026Problem with the configuration.
1508A parameter on the payment call is invalid, check the Payment Solution ResponseSIS0617Error in the DS_MERCHANT_EXCEP_SCA parameter is of type MIT and there is no COF or payment by reference data.
1513Unable to process this operation please check the Payment Solution Response9298You cannot perform this type of operation (Contact your institution).
1513Unable to process this operation please check the Payment Solution ResponseBIZ00007Transaction not allowed.
1513Unable to process this operation please check the Payment Solution ResponseSIS0298You cannot perform this type of operation (Contact your institution).
1520Unsupported API request. You are not registered to use this API9218The merchant does not allow secure input/transaction operations.
1520Unsupported API request. You are not registered to use this APISIS0218The merchant does not allow secure transactions for entries
1524The provided transaction reference has already been used for another transaction. You must provide a unique value for each request9051Repeated order number error
1524The provided transaction reference has already been used for another transaction. You must provide a unique value for each request913Repeated order
1524The provided transaction reference has already been used for another transaction. You must provide a unique value for each requestSIS0051Repeated order number error
1541The transaction was not completed in the permitted time and has expiredBIZ00010Service call exceeded the set time
1542Transaction was manually cancelled or declined by the merchant9928Override of deferred authorization by SIS (batch process)
1542Transaction was manually cancelled or declined by the merchant9929Deferred authorization cancellation performed by the merchant
1548The third party processor has declined the transaction9676Bizum. The transaction is rejected by the processor.
1548The third party processor has declined the transaction9966BIZUM has returned a KO on the authorization
1548The third party processor has declined the transactionSIS0093Issuer refusal
1548The third party processor has declined the transactionSIS0676Bizum. The processor rejects the transaction.
1610A parameter on the payment call is invalid, check the Payment Solution ResponseSIS0075Merchant needs to review how it is sending the order number.
1611The refund was unable to be processed. Check Payment Solution ResponseSIS0054There is no transaction on which to make the refund
1612The orderID does not existSIS0059Check that the transaction exists
1612The orderID does not existSIS0060Check that the confirmation exists
1634Transaction pending to be processed by the Payment Solution9998Transaction in the process of requesting card details
5031Parameter with invalid formatBIZ00002Some parameter format is incorrect.
5037There is a parameter in the request that is mandatoryBIZ00001Mandatory input parameter not completed.
5037There is a parameter in the request that is mandatoryBIZ90001Parameter DS_MERCHANT_BIZUM_MOBILENUMBER not specified
8003Authentication not completed. Check Service ResponseBIZ00225Authentication by request to pay has not been completed successfully.
8006Cancelled by requestor9673Bizum. Transaction cancelled. The user does not wish to continue.
8006Cancelled by requestor9674Bizum. Payment rejected by requestor.
8006Cancelled by requestor9675Bizum. Charge rejected by requestor.
8006Cancelled by requestor9915At the user’s request, the payment has been cancelled.
8006Cancelled by requestorSIS0673Bizum. Transaction cancelled. The user does not wish to continue.
8006Cancelled by requestorSIS0674Bizum. Credit rejected by requestor.
8006Cancelled by requestorSIS0675Bizum. Charge rejected by requestor.
8019Security failureBIZ000063DES or MAC X9.19 security error.
8019Security failureSIS0042Error in the calculation of the signature.
8020Service system error. Check Service Response9040The merchant has an error in the configuration, you have to talk to your bank.
8020Service system error. Check Service Response909System error
8020Service system error. Check Service Response9475NotDefined
8020Service system error. Check Service ResponseBIZ00005Internal system error.
8020Service system error. Check Service ResponseSIS0040The merchant has an error in the configuration, you have to talk to your entity.
8020Service system error. Check Service ResponseSIS0881The client of the transaction has not been authenticated.
8032Authentication error184The system is busy, try again later.
8032Authentication error944Incorrect session
8032Authentication error9672Bizum. Authentication failure. Blocked after three attempts.
8032Authentication errorBIZ00213Authentication error in the request received. Failure in security sequence.
8032Authentication errorBIZ00224ntity response to RTP authentication is KO.
8032Authentication errorSIS0672Bizum. Authentication failure. Blocking after three attempts.
9000Element not foundBIZ00003Element not found
9002Payee not foundBIZ00008The payee was not found.
9003Payer not foundBIZ00009The payer was not found
Comparte este documento
Tabla de Contenidos

Consulta la documentación de las distintas secciones de integraciones:

Comienza a integrar

undraw_add_to_cart_re_wrdo 1 (1) (1)

Plugins para CMS

Complementa la integración

SDKs

Métodos de pago

Herramientas

Addon Payments

Consulta la documentación de Addon Payments. Aquí tienes las distintas secciones:

Integraciones

Consultas frecuentes

Portal Backoffice

Cyberpac

We are currently working on the English version of the Cyberpac documentation. You can view the Spanish version using the buttons below:

Canales BackOffice Portal

Plugins integration

Custom integrations

POS integrated Payments

Create a solution that will help you automate processes. You can even add payment processes on physical terminals.

Payment Integrated with Android POS

Payment Integrated with Smartphone POS

POS Data sheets

Addon Payments

Comercia Global Payments has several integration options so you can choose the most efficient one for you.

Integrations

Frequently Asked Questions

BackOffice Portal

Consult the documentation of the different integrations sections:​

Start integration

undraw_add_to_cart_re_wrdo 1 (1) (1)

CMS Plugins

Complement your integration

SDKs

Payment Methods

Tools