PPRO gateway guide
Adding a PPRO Gateway
curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
<gateway_type>ppro</gateway_type>
<contract_id>Your contract id</contract_id>
</gateway>'<gateway>
<token>RicQLGz0JoFtXQpb4CfDeK2cuPH</token>
<gateway_type>ppro</gateway_type>
<name>PPRO</name>
<description nil="true"/>
<merchant_profile_key nil="true"/>
<sub_merchant_key nil="true"/>
<contract_id>Your contract id</contract_id>
<characteristics>
<supports_purchase type="boolean">false</supports_purchase>
<supports_authorize type="boolean">false</supports_authorize>
<supports_capture type="boolean">false</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">false</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">false</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
<supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">false</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">false</supports_network_tokenization>
<supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
<supports_transaction_retry type="boolean">false</supports_transaction_retry>
<supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
</characteristics>
<credentials>
<credential>
<name>contract_id</name>
<value>Your contract id</value>
</credential>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>merchant_refund_id</gateway_specific_field>
<gateway_specific_field>selling_point</gateway_specific_field>
<gateway_specific_field>sold_service</gateway_specific_field>
<gateway_specific_field>preferred_language</gateway_specific_field>
<gateway_specific_field>merchant_logo_url</gateway_specific_field>
<gateway_specific_field>render_type</gateway_specific_field>
<gateway_specific_field>beneficiary_name</gateway_specific_field>
<gateway_specific_field>beneficiary_id</gateway_specific_field>
<gateway_specific_field>beneficiary_address</gateway_specific_field>
<gateway_specific_field>beneficiary_country_code</gateway_specific_field>
<gateway_specific_field>refund_bank_name</gateway_specific_field>
<gateway_specific_field>refund_account_number</gateway_specific_field>
<gateway_specific_field>refund_bank_agency</gateway_specific_field>
<gateway_specific_field>due_date</gateway_specific_field>
<gateway_specific_field>app_to_app_url</gateway_specific_field>
<gateway_specific_field>shopper_reference</gateway_specific_field>
<gateway_specific_field>company</gateway_specific_field>
<gateway_specific_field>tax_amount</gateway_specific_field>
<gateway_specific_field>payment_method_category</gateway_specific_field>
<gateway_specific_field>emd</gateway_specific_field>
<gateway_specific_field>hpp_title</gateway_specific_field>
<gateway_specific_field>logo_url</gateway_specific_field>
<gateway_specific_field>order_items</gateway_specific_field>
<gateway_specific_field>customer</gateway_specific_field>
<gateway_specific_field>purchase_type</gateway_specific_field>
<gateway_specific_field>background_images</gateway_specific_field>
<gateway_specific_field>terms_accepted</gateway_specific_field>
<gateway_specific_field>p24_method</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>bancontact</payment_method>
<payment_method>blik</payment_method>
<payment_method>boleto_bancario</payment_method>
<payment_method>ideal</payment_method>
<payment_method>klarna</payment_method>
<payment_method>klarna_pay_now</payment_method>
<payment_method>multibanco</payment_method>
<payment_method>oxxo</payment_method>
<payment_method>pix</payment_method>
<payment_method>sepa_direct_debit</payment_method>
<payment_method>sofort</payment_method>
<payment_method>trustly</payment_method>
<payment_method>eps</payment_method>
<payment_method>p24</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2023-07-14T19:31:01Z</created_at>
<updated_at type="dateTime">2023-07-14T19:31:01Z</updated_at>
</gateway>The Spreedly PPRO Gateway is intended to provide a consistent and convenient way to transact using payment methods other than credit cards. We currently support fourteen different local payment methods (LPMs). Most of these LPMs require sending your customer to a page hosted by a backend processor in order to complete the payment process (such as a mandate form in case of SEPA).
Local Payment Methods
Boleto Bancario
Boleto Bancario
Parameters
| Payment Method Fields | Description |
|---|---|
email | RFC compliant email address of the account holder |
document_id | Consumer’s CPF or CNPJ tax id |
zip | 8 digit post code of the billing address |
city | City of the billing address (2-30 characters) |
state | Brazilian state of the billing address; 2 letter-code |
address1 | Street of the billing address (2-50 characters) |
| Gateway Specific Fields | M/O/C | Description |
|---|---|---|
merchant_logo_url | O | Bradesco-only The URL of the logo to be displayed on the payment page. Max logo size: W=1200, H=627. Max URL characters is 255. |
due_date | O | Due date in YYYY-MM-DD format. Defaults to NOW + 3 days |
beneficiary | O | Bradesco-only The beneficiary of the payment - for example, the merchant’s name and order number |
render_type | O | How the Boleto will be rendered: as PDF or HTML. Default: PDF |
For further reference go to: Payment Method Integration - Boleto Bancario
Bancontact
Bancontact
Bancontact via PPRO is a Belgium-focused bank payment method that lets customers pay directly from their bank account using a secure redirect or app-based flow.
In a typical PPRO integration, when a customer selects Bancontact at checkout, our system creates a transaction and receives a redirect URL. The customer is then sent to their banking app or Bancontact environment to authenticate the payment (via mobile app, QR code, or bank login). Once the payment is authorized, the user is redirected back to our site, and you receive the final status via webhook. Payments are usually real-time or near real-time, making it reliable for immediate confirmation
| Constraints | Value |
|---|---|
| Countries | BE |
| Currencies | EUR |
| Refund | Full, Partial, Multiple Partial |
Create Bancontact Payment Method
API Request
POST /v1/payment_methods.json{
"payment_method": {
"payment_method_type": "bancontact",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"country": "BE",
"document_id": "11144477737",
"email": "[email protected]"
}
}{
"transaction": {
"token": "3XGJSKDRAK9AW9Y75DC9K5P89C",
"created_at": "2026-03-26T12:10:15Z",
"updated_at": "2026-03-26T12:10:15Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KMN0TTFKY3MNX71442PD2G1H",
"created_at": "2026-03-26T12:10:15.410Z",
"updated_at": "2026-03-26T12:10:15.410Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "BE",
"phone_number": null,
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "bancontact",
"errors": [],
"document_id": "7737"
}
}
}Create Bancontact Purchase Method
API Request
POST /v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{bancontact_payment_method_token}}", //Token of the bancontact PM used
"amount": 1055,
"currency_code": "EUR",
"order_id": "J2wkc3cdDaJS",
"redirect_url": "https://example.ngrok.app", //Merchant URL where the buyer is redirected after completing bancontact flow
"callback_url": "https://example.ngrok.app"
}
}//Successful Response (Purchase – Pending). State is pending immediately after the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:31:08Z",
"updated_at": "2026-03-23T13:31:10Z",
"succeeded": false,
"state": "pending",
"token": "NKr5KdwGYMCHcGzOV8fzoTZQpcT",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"country": "BE",
"payment_purpose": "710141M0 SPREEDLYTEST",
"bep_url": "BEP://1BC.SANDBOX.CP-PL.PPRO.COM/BEP/LC/1WBUWE5I21VMPDMCC5JRP59U6EKBAIM3R/a$LNCU37SBR63RUS4BJ4K3TVA2"
}
},
"gateway_transaction_id": "150373369641",
"sub_merchant_key": null,
"gateway_latency_ms": 1492,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "EUR",
"reference": "150373369641",
"setup_verification": "KK0X4sUUiZyN8vBK7lUGIerwuITWcvfD",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "3J9789KVDW9F0BDZ4YDQFHB4C8",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:31:10Z",
"updated_at": "2026-03-23T13:31:10Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfUkJrcnV6dWR6VXVzbWdFMFI3VVZnIn19.m-sr8vOAsfYsXDLtKrIEemw9Rgy65Taa9GVlOFHAk4D_W_e64uULl8BHMMxmPyAZ8IsiMyIEQUUfKmE_vRi0ig"
},
"shipping_address": {
"name": "Manuela Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://example.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://example.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfUkJrcnV6dWR6VXVzbWdFMFI3VVZnIn19.m-sr8vOAsfYsXDLtKrIEemw9Rgy65Taa9GVlOFHAk4D_W_e64uULl8BHMMxmPyAZ8IsiMyIEQUUfKmE_vRi0ig",
"callback_url": "https://example.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:31:10Z",
"updated_at": "2026-03-23T13:31:10Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfUkJrcnV6dWR6VXVzbWdFMFI3VVZnIn19.m-sr8vOAsfYsXDLtKrIEemw9Rgy65Taa9GVlOFHAk4D_W_e64uULl8BHMMxmPyAZ8IsiMyIEQUUfKmE_vRi0ig"
},
"payment_method": {
"token": "01KMDE6FKRD13BH18Q22Y1QHQJ",
"created_at": "2026-03-23T13:29:53.528Z",
"updated_at": "2026-03-23T13:29:53.528Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "bancontact",
"errors": []
}
}
}//Successful Response (Purchase – success after webhook).state is succeeded after the customer completes the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-26T12:19:44Z",
"updated_at": "2026-03-26T13:12:48Z",
"succeeded": true,
"state": "succeeded",
"token": "MYI2HjH23WBiWkIvA2T0h6G3Rlg",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "WAITING",
"channel": "testchannel",
"country": "BE",
"payment_purpose": "71014NW3 SPREEDLYTEST",
"bep_url": "BEP://1BC.SANDBOX.CP-PL.PPRO.COM/BEP/LC/29S0X1TKIC7XN7TKOF794O1Z1TDUC94YP/a$A5KVNUJITCCTYW3VCWXZD4ZP",
"bic": "BBRUBEBBXXX",
"card_expiry": "2701",
"card_masked_pan": "41111111XXXXXX1111",
"card_bin": "41111111",
"last_four": "1111"
}
},
"gateway_transaction_id": "150374300108",
"sub_merchant_key": null,
"gateway_latency_ms": 710,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "EUR",
"reference": "150374300108",
"setup_verification": "zwyJXQSXWjHrJatWofC9tW4EIjsk39DN",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "5HQY9SMBPM9NFS04WQAD172CW4",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:12:48Z",
"updated_at": "2026-03-26T13:12:48Z",
"status": null
},
"shipping_address": {
"name": "Manuela Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://example.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://example.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfYnNKb1hiM3lCbHpFcUFSMlI1d1VhIn19.LAvnFwGLDmZqw6B09STCMdJdEOEXdR5taHO3S8jWS8ovtiTea7WjjkJIarjRxim3VcnuoVlbow6HWdzOqzUz1g",
"callback_url": "https://example.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T12:19:45Z",
"updated_at": "2026-03-26T13:12:48Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfYnNKb1hiM3lCbHpFcUFSMlI1d1VhIn19.LAvnFwGLDmZqw6B09STCMdJdEOEXdR5taHO3S8jWS8ovtiTea7WjjkJIarjRxim3VcnuoVlbow6HWdzOqzUz1g"
},
"redirect_response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:12:48Z",
"updated_at": "2026-03-26T13:12:48Z",
"status": null
},
"payment_method": {
"token": "01KMN0TTFKY3MNX71442PD2G1H",
"created_at": "2026-03-26T12:10:15.410Z",
"updated_at": "2026-03-26T12:10:15.410Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "bancontact",
"errors": []
}
}
}//Declined Response (Purchase – User Declined). state is gateway_processing_failed after the customer aborts the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-26T13:15:32Z",
"updated_at": "2026-03-26T13:15:54Z",
"succeeded": false,
"state": "gateway_processing_failed",
"token": "Ms5M9n2U4LxIs1zyVNGTtkeAE08",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"country": "BE",
"payment_purpose": "71014O81 SPREEDLYTEST",
"bep_url": "BEP://1BC.SANDBOX.CP-PL.PPRO.COM/BEP/LC/1MHS2A911SE9YCOWFAOG3KYSXM59GSW32/a$HYA7F5JJLAKRDKXMCFF6TLNX",
"error_message": "Transaction aborted by user",
"fail_reason": "USER_ABORT"
}
},
"gateway_transaction_id": "150374314847",
"sub_merchant_key": null,
"gateway_latency_ms": 628,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "EUR",
"reference": "150374314847",
"setup_verification": "7gl6aikIupKVbkZFR63I2qM6ybaeS6Jg",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message": "The payment was cancelled.",
"gateway_token": "5HQY9SMBPM9NFS04WQAD172CW4",
"gateway_type": "ppro",
"response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:54Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null
},
"shipping_address": {
"name": "Manuela Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://example.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://example.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfRms2dkpDMlpvWGNUM0h1d25VZDVuIn19.Jv-pmvBfOXBspPYLzSEwETtgMqOkXqzHPw_J81D_W8uudKSfrIDo5nf80D-WcRWiqduze9xtI7H6WfJLIlwiyQ",
"callback_url": "https://example.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:34Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfRms2dkpDMlpvWGNUM0h1d25VZDVuIn19.Jv-pmvBfOXBspPYLzSEwETtgMqOkXqzHPw_J81D_W8uudKSfrIDo5nf80D-WcRWiqduze9xtI7H6WfJLIlwiyQ"
},
"redirect_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:54Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null
},
"callback_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:53Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null
},
"payment_method": {
"token": "01KMN0TTFKY3MNX71442PD2G1H",
"created_at": "2026-03-26T12:10:15.410Z",
"updated_at": "2026-03-26T13:12:48.393Z",
"email": "[email protected]",
"data": null,
"storage_state": "used",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": "2026-03-26T13:12:48.000Z",
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "bancontact",
"errors": []
}
}
}Refunds
Refunds are only allowed after a successful purchase
Full Refund: Refunds are processed as credit transactions. Bancontact refunds follow standard Ppro refund flow
Partial Refund: You can perform multiple partial refunds until the total equals the actual transaction amount.
POST /v1/transactions/{{successful_transaction}}/credit.json{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:34:49Z",
"updated_at": "2026-03-23T13:34:50Z",
"succeeded": true,
"state": "succeeded",
"token": "81zRVLjpY2LOTFZsKdgY1s3wKsv",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"bic": "BBRUBEBBXXX",
"country": "BE",
"payment_purpose": "Refund"
}
},
"gateway_transaction_id": "1518867500",
"sub_merchant_key": null,
"gateway_latency_ms": 1084,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 1055,
"local_amount": null,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "3J9789KVDW9F0BDZ4YDQFHB4C8",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:34:50Z",
"updated_at": "2026-03-23T13:34:50Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "NKr5KdwGYMCHcGzOV8fzoTZQpcT"
}
}{
"transaction": {
"amount": 500,
"currency_code": "EUR",
"notification_url": "https://example.ngrok.app/transaction/#{transaction.token}/callback"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:34:49Z",
"updated_at": "2026-03-23T13:34:50Z",
"succeeded": true,
"state": "succeeded",
"token": "81zRVLjpY2LOTFZsKdgY1s3wKsv",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"bic": "BBRUBEBBXXX",
"country": "BE",
"payment_purpose": "Refund"
}
},
"gateway_transaction_id": "1518867500",
"sub_merchant_key": null,
"gateway_latency_ms": 1084,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 500,
"local_amount": null,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "3J9789KVDW9F0BDZ4YDQFHB4C8",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:34:50Z",
"updated_at": "2026-03-23T13:34:50Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "NKr5KdwGYMCHcGzOV8fzoTZQpcT"
}
}BLIK
BLIK
BLIK via PPRO is a popular real-time payment method from Poland, allowing customers to pay using a 6-digit one-time code generated in their mobile banking app.
In a typical PPRO integration, the checkout flow is non-redirect and user-input based. The customer selects BLIK, opens their banking app, generates a one-time code, and enters it on your payment page. Your system then sends this code to PPRO as part of the transaction request. The customer may also need to confirm the payment inside their banking app, depending on the bank. Once approved, the payment is processed instantly, and you receive the final status (success/failure) via API response or webhook.
| Constraints | Values |
|---|---|
| Countries | PL |
| Currencies | PLN |
| Refund | Full, Partial and Multiple Partial |
Create BLIK Payment Method
API Request
POST /v1/payment_methods.json{
"payment_method": {
"payment_method_type": "blik",
"full_name": "Jan Kowalski",
"country": "PL",
"email": "[email protected]",
"retained": true
}
}{
"transaction": {
"token": "2CJS392Q2N8V7AGKTX9P195B24",
"created_at": "2026-03-27T05:19:16Z",
"updated_at": "2026-03-27T05:19:16Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": true,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KMPVPZZ7HK4G2SS6TRYYXYWR",
"created_at": "2026-03-27T05:19:15.943Z",
"updated_at": "2026-03-27T05:19:15.943Z",
"email": "[email protected]",
"data": null,
"storage_state": "retained",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "PL",
"phone_number": null,
"full_name": "Jan Kowalski",
"first_name": "Jan",
"last_name": "Kowalski",
"bic": null,
"payment_method_type": "blik",
"errors": []
}
}
}Create BLIK Purchase Method
API Request
POST /v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{blik_payment_method_token}}",
"amount": 1055,
"currency_code": "PLN",
"order_id": "J2wkc3cdDaJS",
"redirect_url": "https://example.ngrok.app",
"callback_url": "https://example.ngrok.app"
}
}//Successful Response (Purchase – Pending). state is pending immediately after the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-27T05:22:12Z",
"updated_at": "2026-03-27T05:22:13Z",
"succeeded": false,
"state": "pending",
"token": "RR5225wHLqKoh18rW6hfn8ApVhh",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150374520187",
"sub_merchant_key": null,
"gateway_latency_ms": 919,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "PLN",
"reference": "150374520187",
"setup_verification": "OgslN21qQNS4ftsnu1gGY6JVeVfGvul5",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "6PD4KHJRS69DKB9QE9ZHFXF9TT",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:22:13Z",
"updated_at": "2026-03-27T05:22:13Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/form-post?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfbVZrcHRBVFpRclZLZWlta0lsVzRBIn19.Yz64RQ0pVJlac-W6SCSTgcN-lWDHD6haLZ9E_vfIoVgqcchSM5tOR5UwukCHFbLWDCEgJ7wdyK9wcJLUphEFAQ"
},
"shipping_address": {
"name": "Jan Kowalski",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://sajjan.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://sajjan.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/form-post?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfbVZrcHRBVFpRclZLZWlta0lsVzRBIn19.Yz64RQ0pVJlac-W6SCSTgcN-lWDHD6haLZ9E_vfIoVgqcchSM5tOR5UwukCHFbLWDCEgJ7wdyK9wcJLUphEFAQ",
"callback_url": "https://sajjan.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:22:13Z",
"updated_at": "2026-03-27T05:22:13Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/form-post?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfbVZrcHRBVFpRclZLZWlta0lsVzRBIn19.Yz64RQ0pVJlac-W6SCSTgcN-lWDHD6haLZ9E_vfIoVgqcchSM5tOR5UwukCHFbLWDCEgJ7wdyK9wcJLUphEFAQ"
},
"payment_method": {
"token": "01KMPVPZZ7HK4G2SS6TRYYXYWR",
"created_at": "2026-03-27T05:19:15.943Z",
"updated_at": "2026-03-27T05:19:15.943Z",
"email": "[email protected]",
"data": null,
"storage_state": "retained",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"full_name": "Jan Kowalski",
"first_name": "Jan",
"last_name": "Kowalski",
"bic": null,
"payment_method_type": "blik",
"errors": []
}
}
}//Successful Response (Purchase – success after webhook). state is succeeded after the customer completes the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-27T05:22:12Z",
"updated_at": "2026-03-27T05:22:47Z",
"succeeded": true,
"state": "succeeded",
"token": "RR5225wHLqKoh18rW6hfn8ApVhh",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150374520187",
"sub_merchant_key": null,
"gateway_latency_ms": 603,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "PLN",
"reference": "150374520187",
"setup_verification": "OgslN21qQNS4ftsnu1gGY6JVeVfGvul5",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6PD4KHJRS69DKB9QE9ZHFXF9TT",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:22:47Z",
"updated_at": "2026-03-27T05:22:47Z",
"status": null
},
"shipping_address": {
"name": "Jan Kowalski",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://sajjan.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://sajjan.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/form-post?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfbVZrcHRBVFpRclZLZWlta0lsVzRBIn19.Yz64RQ0pVJlac-W6SCSTgcN-lWDHD6haLZ9E_vfIoVgqcchSM5tOR5UwukCHFbLWDCEgJ7wdyK9wcJLUphEFAQ",
"callback_url": "https://sajjan.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:22:13Z",
"updated_at": "2026-03-27T05:22:47Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/form-post?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfbVZrcHRBVFpRclZLZWlta0lsVzRBIn19.Yz64RQ0pVJlac-W6SCSTgcN-lWDHD6haLZ9E_vfIoVgqcchSM5tOR5UwukCHFbLWDCEgJ7wdyK9wcJLUphEFAQ"
},
"callback_response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:22:47Z",
"updated_at": "2026-03-27T05:22:47Z",
"status": null
},
"payment_method": {
"token": "01KMPVPZZ7HK4G2SS6TRYYXYWR",
"created_at": "2026-03-27T05:19:15.943Z",
"updated_at": "2026-03-27T05:19:15.943Z",
"email": "[email protected]",
"data": null,
"storage_state": "retained",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"full_name": "Jan Kowalski",
"first_name": "Jan",
"last_name": "Kowalski",
"bic": null,
"payment_method_type": "blik",
"errors": []
}
}
}//Declined Response (Purchase – User Declined). state is gateway_processing_failed after the customer aborts the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-27T05:24:52Z",
"updated_at": "2026-03-27T05:25:16Z",
"succeeded": false,
"state": "gateway_setup_failed",
"token": "Ze1bIUYZNTUMnuI5CRCLLw7WzgW",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"error_message": "USER_DECLINED",
"fail_reason": "USER_ABORT"
}
},
"gateway_transaction_id": "150374520444",
"sub_merchant_key": null,
"gateway_latency_ms": 577,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "PLN",
"reference": "150374520444",
"setup_verification": "caW22uiqSv2yFak2ui7dYk5NzlYBIjSh",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message": "The payment was cancelled.",
"gateway_token": "6PD4KHJRS69DKB9QE9ZHFXF9TT",
"gateway_type": "ppro",
"response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:25:16Z",
"updated_at": "2026-03-27T05:25:16Z",
"status": null
},
"shipping_address": {
"name": "Jan Kowalski",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://sajjan.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://sajjan.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/form-post?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfblB2WXBlTWYzOXVuOXhjS0VTYThBIn19.GOcCXTd0VT2uZqWqdwMRx910yqE8beF_aT3w6e6HFHHYP2VFabzigh0BqwEv3VFGfA4UxjnLQKey0VUSiTsdlw",
"callback_url": "https://sajjan.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:24:53Z",
"updated_at": "2026-03-27T05:25:16Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/form-post?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfblB2WXBlTWYzOXVuOXhjS0VTYThBIn19.GOcCXTd0VT2uZqWqdwMRx910yqE8beF_aT3w6e6HFHHYP2VFabzigh0BqwEv3VFGfA4UxjnLQKey0VUSiTsdlw"
},
"redirect_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:25:15Z",
"updated_at": "2026-03-27T05:25:16Z",
"status": null
},
"callback_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-27T05:25:16Z",
"updated_at": "2026-03-27T05:25:16Z",
"status": null
},
"payment_method": {
"token": "01KMPVPZZ7HK4G2SS6TRYYXYWR",
"created_at": "2026-03-27T05:19:15.943Z",
"updated_at": "2026-03-27T05:22:47.764Z",
"email": "[email protected]",
"data": null,
"storage_state": "retained",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": "2026-03-27T05:22:47.000Z",
"full_name": "Jan Kowalski",
"first_name": "Jan",
"last_name": "Kowalski",
"bic": null,
"payment_method_type": "blik",
"errors": []
}
}
}Refunds
Refunds are only allowed after a successful purchase
Full Refund: Refunds are processed as credit transactions. Blik refunds follow standard Ppro refund flow
Partial Refund: You can perform multiple partial refunds until the total equals the actual transaction amount.
POST /v1/transactions/{{successful_transaction}}/credit.json{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:46:32Z",
"updated_at": "2026-03-23T13:46:33Z",
"succeeded": true,
"state": "succeeded",
"token": "D1BNl2WuGAtHOBVbs1g7ai9sz1M",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {}
},
"gateway_transaction_id": "1518867594",
"sub_merchant_key": null,
"gateway_latency_ms": 1318,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 1055,
"local_amount": null,
"currency_code": "PLN",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "5ADVG8QGKM8YSAGTKJPDA1XZTR",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:46:33Z",
"updated_at": "2026-03-23T13:46:33Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "Ejc81UbzY1WviyqmhDbVRrjZoAE"
}
}{
"transaction": {
"amount": 500,
"currency_code": "PLN",
"notification_url": "https://example.ngrok.app/transaction/#{transaction.token}/callback"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:46:32Z",
"updated_at": "2026-03-23T13:46:33Z",
"succeeded": true,
"state": "succeeded",
"token": "D1BNl2WuGAtHOBVbs1g7ai9sz1M",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {}
},
"gateway_transaction_id": "1518867594",
"sub_merchant_key": null,
"gateway_latency_ms": 1318,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 500,
"local_amount": null,
"currency_code": "PLN",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "5ADVG8QGKM8YSAGTKJPDA1XZTR",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:46:33Z",
"updated_at": "2026-03-23T13:46:33Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "Ejc81UbzY1WviyqmhDbVRrjZoAE"
}
}EPS
EPS
EPS (Electronic Payment Standard) via PPRO is a bank redirect payment method from Austria that enables customers to pay directly through their online banking environment. During checkout, the customer selects EPS and is redirected to their bank’s secure login page, where they authenticate and authorize the payment. After confirmation, the customer is redirected back to the merchant site, while the final transaction status is communicated asynchronously via webhook/notification from PPRO. EPS supports EUR currency, is designed for one-time payments (not recurring), and offers real-time or near real-time confirmation, making it a reliable option for secure bank-based payments without requiring card details
| Constraints | Values |
|---|---|
| Countries | AT |
| Currencies | EUR |
| Refund | Processed via SEPA Credit Transfer. Partial and Multiple Partial refunds supported |
Create EPS Payment Method
API Request
POST /v1/payment_methods.json{
"payment_method": {
"payment_method_type": "eps",
"full_name": "Jan Kowalski",
"country": "AT",
"email": "[email protected]",
"retained": true
}
}{
"transaction": {
"token": "67BPGB4X5F9G08AZCAMSQVCAEW",
"created_at": "2026-03-30T08:10:33Z",
"updated_at": "2026-03-30T08:10:33Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": true,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KMYWPSV9XKRM611DJ6K1PRE5",
"created_at": "2026-03-30T08:10:33.704Z",
"updated_at": "2026-03-30T08:10:33.704Z",
"email": "[email protected]",
"data": null,
"storage_state": "retained",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "AT",
"phone_number": null,
"full_name": "Jan Kowalski",
"first_name": "Jan",
"last_name": "Kowalski",
"bic": null,
"payment_method_type": "eps",
"errors": []
}
}
}Create EPS Purchase Method
API Request
POST /v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{eps_payment_method_token}}",
"amount": 1055,
"currency_code": "EUR",
"order_id": "J2wkc3cdDaJS",
"redirect_url": "https://example.ngrok.app",
"callback_url": "https://example.ngrok.app"
}
}//Successful Response (Purchase – Pending). state is pending immediately after the purchase.
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:31:08Z",
"updated_at": "2026-03-23T13:31:10Z",
"succeeded": false,
"state": "pending",
"token": "NKr5KdwGYMCHcGzOV8fzoTZQpcT",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"country": "BE",
"payment_purpose": "710141M0 SPREEDLYTEST",
"bep_url": "BEP://1BC.SANDBOX.CP-PL.PPRO.COM/BEP/LC/1WBUWE5I21VMPDMCC5JRP59U6EKBAIM3R/a$LNCU37SBR63RUS4BJ4K3TVA2"
}
},
"gateway_transaction_id": "150373369641",
"sub_merchant_key": null,
"gateway_latency_ms": 1492,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "EUR",
"reference": "150373369641",
"setup_verification": "KK0X4sUUiZyN8vBK7lUGIerwuITWcvfD",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "3J9789KVDW9F0BDZ4YDQFHB4C8",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:31:10Z",
"updated_at": "2026-03-23T13:31:10Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfUkJrcnV6dWR6VXVzbWdFMFI3VVZnIn19.m-sr8vOAsfYsXDLtKrIEemw9Rgy65Taa9GVlOFHAk4D_W_e64uULl8BHMMxmPyAZ8IsiMyIEQUUfKmE_vRi0ig"
},
"shipping_address": {
"name": "Manuela Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://example.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://example.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfUkJrcnV6dWR6VXVzbWdFMFI3VVZnIn19.m-sr8vOAsfYsXDLtKrIEemw9Rgy65Taa9GVlOFHAk4D_W_e64uULl8BHMMxmPyAZ8IsiMyIEQUUfKmE_vRi0ig",
"callback_url": "https://example.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:31:10Z",
"updated_at": "2026-03-23T13:31:10Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfUkJrcnV6dWR6VXVzbWdFMFI3VVZnIn19.m-sr8vOAsfYsXDLtKrIEemw9Rgy65Taa9GVlOFHAk4D_W_e64uULl8BHMMxmPyAZ8IsiMyIEQUUfKmE_vRi0ig"
},
"payment_method": {
"token": "01KMDE6FKRD13BH18Q22Y1QHQJ",
"created_at": "2026-03-23T13:29:53.528Z",
"updated_at": "2026-03-23T13:29:53.528Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "eps",
"errors": []
}
}
}iDEAL
iDEAL
iDEAL via PPRO is a bank-based online payment method from Netherlands that allows customers to pay directly from their bank account through a secure redirect flow. When selected at checkout, the customer is redirected to their bank’s online environment (or a bank selection page), where they authenticate and authorize the payment. After completion, the user is redirected back to the merchant site, while the final transaction status is communicated asynchronously via webhook/notification
| Constraints | Values |
|---|---|
| Countries | NL |
| Currencies | EUR |
| Refund | Full, Partial, Multiple partial |
Create iDEAL Payment Method
API Request
POST /v1/payment_methods.json{
"payment_method": {
"payment_method_type": "ideal",
"full_name": "Full Name",
"country_code": "NL"
}
}{
"transaction": {
"token": "32XGNTGYJ29R9TFX04B1XC00H8",
"created_at": "2026-03-30T07:59:15Z",
"updated_at": "2026-03-30T07:59:15Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KMYW23JZFT4XVKDXQ58KN4Z1",
"created_at": "2026-03-30T07:59:15.551Z",
"updated_at": "2026-03-30T07:59:15.551Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "NL",
"phone_number": null,
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"bic": null,
"payment_method_type": "ideal",
"errors": []
}
}
}Create iDEAL Purchase Method
API Request
POST /v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{ideal_pm}}",
"amount": 2500,
"currency_code": "EUR",
"redirect_url": "https://sajjan.ngrok.app",
"callback_url": "https://sajjan.ngrok.app"
}
}//Successful Response (Purchase – Pending). state is pending immediately after the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-30T11:20:59Z",
"updated_at": "2026-03-30T11:21:00Z",
"succeeded": false,
"state": "pending",
"token": "2kp31euLJWoiKKKlu78E8NSApgG",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"country": "NL",
"payment_purpose": "710156Q0 SPREEDLYTEST SUBCREDITOR"
}
},
"gateway_transaction_id": "150375633226",
"sub_merchant_key": null,
"gateway_latency_ms": 1290,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 2500,
"local_amount": null,
"currency_code": "EUR",
"reference": "150375633226",
"setup_verification": "C78MDuVhqRN0sdKb7UguW19D60BHzHE7",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "7C12D4VXXH9W5R9H5YDTHWQFKY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T11:21:00Z",
"updated_at": "2026-03-30T11:21:00Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfVXdDRXl2Qk9aUVBIR3A1NTZYRGYwIn19.QURBE5arYyUs43yRsKgwj-dyGvs1ewfozQlZw_kIec-cabV8tZwOuA8IMqcJGeiyQC6D-Kzyv-eW8Wfdu-1ksA"
},
"shipping_address": {
"name": "Full Name",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfVXdDRXl2Qk9aUVBIR3A1NTZYRGYwIn19.QURBE5arYyUs43yRsKgwj-dyGvs1ewfozQlZw_kIec-cabV8tZwOuA8IMqcJGeiyQC6D-Kzyv-eW8Wfdu-1ksA",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T11:21:00Z",
"updated_at": "2026-03-30T11:21:00Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfVXdDRXl2Qk9aUVBIR3A1NTZYRGYwIn19.QURBE5arYyUs43yRsKgwj-dyGvs1ewfozQlZw_kIec-cabV8tZwOuA8IMqcJGeiyQC6D-Kzyv-eW8Wfdu-1ksA"
},
"callback_url": null,
"payment_method": {
"token": "01KMYW23JZFT4XVKDXQ58KN4Z1",
"created_at": "2026-03-30T07:59:15.551Z",
"updated_at": "2026-03-30T10:48:19.643Z",
"email": null,
"data": null,
"storage_state": "used",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": "2026-03-30T10:48:19.000Z",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"bic": null,
"payment_method_type": "ideal",
"errors": []
}
}
}//Successful Response (Purchase – success after webhook). state is succeeded after the customer completes the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-30T11:20:59Z",
"updated_at": "2026-03-30T11:21:24Z",
"succeeded": true,
"state": "succeeded",
"token": "2kp31euLJWoiKKKlu78E8NSApgG",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"country": "NL",
"payment_purpose": "710156Q0 SPREEDLYTEST SUBCREDITOR",
"bic": "ABNANL2A",
"account_holder": "The dude"
}
},
"gateway_transaction_id": "150375633226",
"sub_merchant_key": null,
"gateway_latency_ms": 759,
"warning": "Unable to perform a redirect because no redirect_url was provided.",
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 2500,
"local_amount": null,
"currency_code": "EUR",
"reference": "150375633226",
"setup_verification": "C78MDuVhqRN0sdKb7UguW19D60BHzHE7",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "7C12D4VXXH9W5R9H5YDTHWQFKY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T11:21:24Z",
"updated_at": "2026-03-30T11:21:24Z",
"status": null
},
"shipping_address": {
"name": "Full Name",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfVXdDRXl2Qk9aUVBIR3A1NTZYRGYwIn19.QURBE5arYyUs43yRsKgwj-dyGvs1ewfozQlZw_kIec-cabV8tZwOuA8IMqcJGeiyQC6D-Kzyv-eW8Wfdu-1ksA",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T11:21:00Z",
"updated_at": "2026-03-30T11:21:24Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfVXdDRXl2Qk9aUVBIR3A1NTZYRGYwIn19.QURBE5arYyUs43yRsKgwj-dyGvs1ewfozQlZw_kIec-cabV8tZwOuA8IMqcJGeiyQC6D-Kzyv-eW8Wfdu-1ksA"
},
"callback_url": null,
"callback_response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T11:21:24Z",
"updated_at": "2026-03-30T11:21:24Z",
"status": null
},
"payment_method": {
"token": "01KMYW23JZFT4XVKDXQ58KN4Z1",
"created_at": "2026-03-30T07:59:15.551Z",
"updated_at": "2026-03-30T10:48:19.643Z",
"email": null,
"data": null,
"storage_state": "used",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": "2026-03-30T10:48:19.000Z",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"bic": null,
"payment_method_type": "ideal",
"errors": []
}
}
}//Declined Response (Purchase – User Declined). state is gateway_processing_failed after the customer aborts the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-30T13:40:10Z",
"updated_at": "2026-03-30T13:40:33Z",
"succeeded": false,
"state": "gateway_processing_failed",
"token": "91bLX7n0FD9zMX9C6xKPbhRt90I",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"country": "NL",
"payment_purpose": "7101576F SPREEDLYTEST SUBCREDITOR",
"error_message": "canceled by consumer",
"fail_reason": "USER_ABORT" //"fail_reason": "USER_ABORT" occurs when the user aborts the payment after visiting the checkout_url page
}
},
"gateway_transaction_id": "150375681150",
"sub_merchant_key": null,
"gateway_latency_ms": 708,
"warning": "Unable to perform a redirect because no redirect_url was provided.",
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 2500,
"local_amount": null,
"currency_code": "EUR",
"reference": "150375681150",
"setup_verification": "kwnOtU5NIoH02okDTglmrk9wujsWEj9w",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message": "The payment was cancelled.",
"gateway_token": "7C12D4VXXH9W5R9H5YDTHWQFKY",
"gateway_type": "ppro",
"response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T13:40:33Z",
"updated_at": "2026-03-30T13:40:33Z",
"status": null
},
"shipping_address": {
"name": "Full Name",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfWFFRMzVXY2taSEkyblVtblpaYlFLIn19.682Rv1u_ksss9prGqonpJCgaCmFmgqlg_SiRLHMnzofDz0PMnefOUFGOmOTv1dT4yoxJrtGZ_3lFUB2_XqmHBw",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T13:40:11Z",
"updated_at": "2026-03-30T13:40:33Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfWFFRMzVXY2taSEkyblVtblpaYlFLIn19.682Rv1u_ksss9prGqonpJCgaCmFmgqlg_SiRLHMnzofDz0PMnefOUFGOmOTv1dT4yoxJrtGZ_3lFUB2_XqmHBw"
},
"callback_url": null,
"callback_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT", //"error_code": "USER_ABORT" occurs when the user aborts the payment after visiting the checkout_url page
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T13:40:33Z",
"updated_at": "2026-03-30T13:40:33Z",
"status": null
},
"payment_method": {
"token": "01KMYW23JZFT4XVKDXQ58KN4Z1",
"created_at": "2026-03-30T07:59:15.551Z",
"updated_at": "2026-03-30T11:21:24.699Z",
"email": null,
"data": null,
"storage_state": "used",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": "2026-03-30T11:21:24.000Z",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"bic": null,
"payment_method_type": "ideal",
"errors": []
}
}
}Refunds
Refunds are only allowed after a successful purchase
Full Refund: Refunds are processed as credit transactions. ideal refunds follow standard Ppro refund flow
Partial Refund: You can perform multiple partial refunds until the total equals the actual transaction amount
POST /v1/transactions/{{successful_transaction}}/credit.json{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-30T11:24:50Z",
"updated_at": "2026-03-30T11:24:51Z",
"succeeded": true,
"state": "succeeded",
"token": "7f6qfAENCgnyD6fTpuaYgYaOENz",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"bic": "ABNANL2A",
"country": "NL",
"account_holder": "The dude",
"payment_purpose": "710156Q0 SPREEDLYTEST SUBCREDITOR"
}
},
"gateway_transaction_id": "1518905386",
"sub_merchant_key": null,
"gateway_latency_ms": 979,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 2500,
"local_amount": null,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "7C12D4VXXH9W5R9H5YDTHWQFKY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T11:24:51Z",
"updated_at": "2026-03-30T11:24:51Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "2kp31euLJWoiKKKlu78E8NSApgG"
}
}{
"transaction": {
"amount": 400,
"currency_code": "EUR",
"notification_url": "https://example.ngrok.app/transaction/#{transaction.token}/callback"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-30T13:43:52Z",
"updated_at": "2026-03-30T13:43:53Z",
"succeeded": true,
"state": "succeeded",
"token": "PkxNM5RXotnICaziVSeXegTviW5",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"bic": "ABNANL2A",
"country": "NL",
"account_holder": "The dude",
"payment_purpose": "7101576M SPREEDLYTEST SUBCREDITOR"
}
},
"gateway_transaction_id": "1518906174",
"sub_merchant_key": null,
"gateway_latency_ms": 904,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 400,
"local_amount": null,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "7C12D4VXXH9W5R9H5YDTHWQFKY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-30T13:43:53Z",
"updated_at": "2026-03-30T13:43:53Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "IyP9eTeSTQq8eIEqTTmAl6fgAS5"
}
}Klarna
Klarna
Available country code |
Fair Financing: |
Refund |
Full, Partial and Multiple partial |
Parameters
| Payment Method Fields | Description |
|---|---|
|
The billing address. It is passed as a URL-encoded serialized JSON string (see Klarna documentation about the billing address). |
|
The shipping address. Passed as URL-encoded serialized JSON string. Defaults to transientin.billingaddress |
| Gateway Specific Fields | M/O/C | Description |
|---|---|---|
|
M |
The total tax amount of the order in the currency’s minor units. This information is essential to provide detailed purchase information to the consumer (e.g., on the invoice). |
|
O |
The payment method category:
|
|
O |
Stands for “Extra Merchant Data”, a pass-through field containing additional information about the merchant and the transaction. It is passed as an URL-encoded JSON string. Corresponds to the attachment.body of the Create Payment Session call. |
|
O |
The title of the hosted payment page, displayed in the browser’s tab. If not set, defaults to the title set in the merchant configuration provided during the boarding process. |
|
O |
URL of the merchant’s logo to be displayed on Klarna’s hosted payment page. If not set, defaults to the logo set in the merchant configuration. |
|
M |
The items being purchased. Passed as URL-encoded serialized JSON string (see Klarna documentation about Order Lines) |
|
O |
Consumer information to be forwarded to Klarna as a URL-encoded serialized JSON string (see Klarna documentation about Customer data). |
|
O |
The type of purchase being made. Defines, for example, the label of the button on Klarna’s hosted payment page:
|
|
O |
The images to be used as a background on Klarna’s payment page (the image best matching the resolution will be used). This is a pass-through field. Check Klarna’s documentation for more information about the correct format. This value can also be set in the merchant configuration. |
For further reference go to: Payment Method Integration - Klarna
For information regarding branding, see the Klarna official website.
Klarna Pay
Klarna Pay
| Available country code | AT, CH, DE, SE, GB |
| Refund | Full, Partial and Multiple partial |
Important Note: Transactions may change from any state at any time. This change occurs especially from a FAILED to a SUCCEEDED state.
Parameters using same model as Klarna.
For further reference go to: Payment Method Integration - Klarna Pay
Multibanco
Multibanco
Multibanco via PPRO allows merchants to accept payments from consumers in Portugal via online banking or cash payment at a Multibanco ATM. The consumer is redirected to a PPRO-hosted page where they receive a supplier ID and payment reference, which they use to complete payment through their bank's online portal or at any Multibanco ATM. This document outlines the API requests, required fields, and expected responses for integrating Multibanco through the PPRO gateway on Spreedly
| Constraints | Value |
|---|---|
| Countries | PT (Portugal only) |
| Currencies | EUR only |
| Refund | Full, partial, and multiple partial |
Create Multibanco Payment Method
API Request
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"payment_method": {
"payment_method_type": "multibanco", //Must be "multibanco"
"full_name": "Full Name", //customer's full name
"country": "PT" //must be PT only
}
}{
"transaction": {
"token": "3N2CK9KZEA98J995YT1QPE33ZQ",
"created_at": "2026-03-19T10:52:09Z",
"updated_at": "2026-03-19T10:52:09Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KM2VJS3X681T148HPYCWKQTC", //(string):Unique identifier for payment method
"created_at": "2026-03-19T10:52:09.213Z",
"updated_at": "2026-03-19T10:52:09.213Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"country": "PT",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"payment_method_type": "multibanco",
"errors": []
}
}
}Create Multibanco Transaction
The consumer is redirected to a PPRO-hosted page where they receive a Supplier ID and Payment Reference. They use these to complete payment via online banking or at a Multibanco ATM
API Request
POST /v1/gateways/{{gateway_token}}/purchase.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {
"payment_method_token": "{{multibanco_payment_method_token}}",
"amount": 1000, //Amount in smallest currency unit
"currency_code": "EUR",
"redirect_url": "https://example.com/redirect", //Where to redirect consumer to complete payment
"callback_url": "https://example.com/callback" //For async payment confirmation from Spreedly
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T10:52:12Z",
"updated_at": "2026-03-19T10:52:13Z",
"succeeded": false,
"state": "pending", //Will be "pending" — payment is confirmed asynchronously once the consumer completes it
"token": "01KM2VJWC12K4VF49WF3X5M8EZ", //Unique transaction identifier
"transaction_type": "OffsitePurchase",
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150372082816",
"amount": 1000,
"currency_code": "EUR",
"reference": "150372082816",
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "40P2RJS8Z8963AXDKB9QC3E2EM",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"pending": true,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T10:52:13Z",
"updated_at": "2026-03-19T10:52:13Z",
"checkout_url": "https://mp8tn4c192.execute-api.eu-central-1.amazonaws.com/default/authenticator.html?payment-charge-id=charge_a9VfG3H2KApWwfYM2nXJ0"
},
"checkout_url": "https://mp8tn4c192.execute-api.eu-central-1.amazonaws.com/default/authenticator.html?payment-charge-id=charge_a9VfG3H2KApWwfYM2nXJ0",
"redirect_url": "https://example.com/redirect",
"callback_url": "https://example.com/callback",
"attempt_3dsecure": false,
"required_action": "none",
"payment_method": {
"token": "01KM2VJS3X681T148HPYCWKQTC",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"payment_method_type": "multibanco",
"errors": []
}
}
}Refund (Credit) Multibanco Transaction
Multibanco supports full refunds, partial refunds, and multiple partial refunds. Refunds are valid for up to 15 months
POST /v1/transactions/{{transaction_token}}/credit.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {}
}//Status Code: 201 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T10:52:26Z",
"updated_at": "2026-03-19T10:52:26Z",
"succeeded": true,
"state": "succeeded",
"token": "01KM2VK9V5X3H8169DEWD31J5F",
"transaction_type": "Credit",
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {}
},
"gateway_transaction_id": "1518847302",
"amount": 1000,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "40P2RJS8Z8963AXDKB9QC3E2EM",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"pending": false,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T10:52:26Z",
"updated_at": "2026-03-19T10:52:26Z"
},
"reference_token": "01KM2VJWC12K4VF49WF3X5M8EZ"
}
}Webhook Notifications and Status Mapping
PPRO → Spreedly (notification_url)
Once the consumer completes payment (via online banking or ATM), Multibanco notifies PPRO, which sends an asynchronous update to Spreedly.
Spreedly:
- Receives the PPRO notification.
- Maps the PPRO/Multibanco status to Spreedly transaction states.
- Updates the original purchase transaction (previously pending).
- Triggers a callback to the merchant's callback_url with the updated status
Spreedly → Merchant (callback_url)
When Spreedly updates the transaction to succeeded or failed, it will POST to the merchant’s callback_url with the final transaction state
Oxxo
Oxxo
OXXO is a cash-based payment method in Mexico that allows customers to pay online orders offline at physical OXXO convenience stores.
In a PPRO integration, when a customer selects OXXO at checkout, a payment voucher (payslip/barcode) is generated containing the transaction details and a unique reference number. The customer can then print or save this voucher and visit an OXXO store to pay in cash.
Once the payment is completed at the store, PPRO receives confirmation and notifies the merchant asynchronously via webhook/notification, after which the merchant can fulfill the order
| Constraints | Value |
|---|---|
| Countries | MX |
| Currencies | MXN |
| Refund | Full, partial, and multiple partial |
Create Payment Method
API Request
POST /v1/payment_methods.json{
"payment_method": {
"payment_method_type": "oxxo",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"country": "MX",
"document_id": "11144477737",
"email": "[email protected]"
}
}{
"transaction": {
"token": "1ZV3MFTV7W9SDAXDYWQ08WVE3Y",
"created_at": "2026-03-27T11:47:42Z",
"updated_at": "2026-03-27T11:47:42Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KMQHY7Z6RBE38DB5PBE117BB",
"created_at": "2026-03-27T11:47:42.182Z",
"updated_at": "2026-03-27T11:47:42.182Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "MX",
"phone_number": null,
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "oxxo",
"errors": [],
"document_id": "7737"
}
}
}Create Oxxo Purchase Method
API Request
POST /v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{payment_method_token}}",
"amount": 1055,
"currency_code": "MXN",
"order_id": "J2wkc3cdDaJS",
"redirect_url": "https://sajjan.ngrok.app",
"callback_url": "https://sajjan.ngrok.app"
}
}//Successful Response (Purchase – Pending). state is pending immediately after the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T12:10:31Z",
"updated_at": "2026-03-23T12:10:32Z",
"succeeded": false,
"state": "pending",
"token": "VULMCk5T68mmurTzzbPIja6rXzP",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"document_code": "46150373348314820260327000105556",
"document": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2JhcmNvZGUvODUzOWE4M2QyN2Y0M2JmNzgyZjA2ZWU3YTE0MGQ0YTIifX0.C9cHvONowAuarubU_8L5Ul189LWD9vIrxadVl7tsHjmI4MAu_kZoCq_vDQG8qu3T0jlvSxP1zpTBHo403c12dg",
"document_image": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2ltYWdlLzg1MzlhODNkMjdmNDNiZjc4MmYwNmVlN2ExNDBkNGEyIn19.lZq8PZ0YLnTLR4uVxGeSQYEtcSPTbEGdmjBC34XiQOZspUUKqEL6tBRdoTyY7ktWEmy-No7jb8HT_tdkFuDIGA"
}
},
"gateway_transaction_id": "150373348314",
"sub_merchant_key": null,
"gateway_latency_ms": 909,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "MXN",
"reference": "150373348314",
"setup_verification": "72QXSftpdKju6GgYvP9qJwTgyZx5Vg3F",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "1H65HXJFWT8NAT9VHZZ3NX3KS9",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T12:10:32Z",
"updated_at": "2026-03-23T12:10:32Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2JhcmNvZGUvODUzOWE4M2QyN2Y0M2JmNzgyZjA2ZWU3YTE0MGQ0YTIifX0.C9cHvONowAuarubU_8L5Ul189LWD9vIrxadVl7tsHjmI4MAu_kZoCq_vDQG8qu3T0jlvSxP1zpTBHo403c12dg"
},
"shipping_address": {
"name": "Manuela Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://sajjan.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://sajjan.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2JhcmNvZGUvODUzOWE4M2QyN2Y0M2JmNzgyZjA2ZWU3YTE0MGQ0YTIifX0.C9cHvONowAuarubU_8L5Ul189LWD9vIrxadVl7tsHjmI4MAu_kZoCq_vDQG8qu3T0jlvSxP1zpTBHo403c12dg",
"callback_url": "https://sajjan.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T12:10:32Z",
"updated_at": "2026-03-23T12:10:32Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2JhcmNvZGUvODUzOWE4M2QyN2Y0M2JmNzgyZjA2ZWU3YTE0MGQ0YTIifX0.C9cHvONowAuarubU_8L5Ul189LWD9vIrxadVl7tsHjmI4MAu_kZoCq_vDQG8qu3T0jlvSxP1zpTBHo403c12dg"
},
"payment_method": {
"token": "01KMD9587GBTVXQZPJXMWKS7D1",
"created_at": "2026-03-23T12:01:50.320Z",
"updated_at": "2026-03-23T12:01:50.320Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "oxxo",
"errors": []
}
}
}//Successful Response (Purchase – success after webhook). state is succeeded after the customer completes the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-26T12:19:44Z",
"updated_at": "2026-03-26T13:12:48Z",
"succeeded": true,
"state": "succeeded",
"token": "MYI2HjH23WBiWkIvA2T0h6G3Rlg",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"document_code": "46150373348314820260327000105556",
"document": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2JhcmNvZGUvODUzOWE4M2QyN2Y0M2JmNzgyZjA2ZWU3YTE0MGQ0YTIifX0.C9cHvONowAuarubU_8L5Ul189LWD9vIrxadVl7tsHjmI4MAu_kZoCq_vDQG8qu3T0jlvSxP1zpTBHo403c12dg",
"document_image": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2ltYWdlLzg1MzlhODNkMjdmNDNiZjc4MmYwNmVlN2ExNDBkNGEyIn19.lZq8PZ0YLnTLR4uVxGeSQYEtcSPTbEGdmjBC34XiQOZspUUKqEL6tBRdoTyY7ktWEmy-No7jb8HT_tdkFuDIGA"
}
},
"gateway_transaction_id": "150374300108",
"sub_merchant_key": null,
"gateway_latency_ms": 710,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "MXN",
"reference": "150374300108",
"setup_verification": "zwyJXQSXWjHrJatWofC9tW4EIjsk39DN",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "5HQY9SMBPM9NFS04WQAD172CW4",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:12:48Z",
"updated_at": "2026-03-26T13:12:48Z",
"status": null
},
"shipping_address": {
"name": "Manuela Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://example.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://example.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfYnNKb1hiM3lCbHpFcUFSMlI1d1VhIn19.LAvnFwGLDmZqw6B09STCMdJdEOEXdR5taHO3S8jWS8ovtiTea7WjjkJIarjRxim3VcnuoVlbow6HWdzOqzUz1g",
"callback_url": "https://example.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T12:19:45Z",
"updated_at": "2026-03-26T13:12:48Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfYnNKb1hiM3lCbHpFcUFSMlI1d1VhIn19.LAvnFwGLDmZqw6B09STCMdJdEOEXdR5taHO3S8jWS8ovtiTea7WjjkJIarjRxim3VcnuoVlbow6HWdzOqzUz1g"
},
"redirect_response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:12:48Z",
"updated_at": "2026-03-26T13:12:48Z",
"status": null
},
"payment_method": {
"token": "01KMN0TTFKY3MNX71442PD2G1H",
"created_at": "2026-03-26T12:10:15.410Z",
"updated_at": "2026-03-26T12:10:15.410Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "oxxo",
"errors": []
}
}
}//Declined Response (Purchase – User Declined). state is gateway_processing_failed after the customer aborts the purchase
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-26T13:15:32Z",
"updated_at": "2026-03-26T13:15:54Z",
"succeeded": false,
"state": "gateway_processing_failed",
"token": "Ms5M9n2U4LxIs1zyVNGTtkeAE08",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"document_code": "46150373348314820260327000105556",
"document": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2JhcmNvZGUvODUzOWE4M2QyN2Y0M2JmNzgyZjA2ZWU3YTE0MGQ0YTIifX0.C9cHvONowAuarubU_8L5Ul189LWD9vIrxadVl7tsHjmI4MAu_kZoCq_vDQG8qu3T0jlvSxP1zpTBHo403c12dg",
"document_image": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfTzJkV3BqWlRnSUplQlhiSkRidElTIiwibCI6Imh0dHBzOi8vYWNvbjQtb3h4by5zYW5kYm94LmxwLWFtZXJpY2FzLnBwcm8uY29tL2ltYWdlLzg1MzlhODNkMjdmNDNiZjc4MmYwNmVlN2ExNDBkNGEyIn19.lZq8PZ0YLnTLR4uVxGeSQYEtcSPTbEGdmjBC34XiQOZspUUKqEL6tBRdoTyY7ktWEmy-No7jb8HT_tdkFuDIGA"
"fail_reason": "USER_ABORT"
}
},
"gateway_transaction_id": "150374314847",
"sub_merchant_key": null,
"gateway_latency_ms": 628,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1055,
"local_amount": null,
"currency_code": "MXN",
"reference": "150374314847",
"setup_verification": "7gl6aikIupKVbkZFR63I2qM6ybaeS6Jg",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message": "The payment was cancelled.",
"gateway_token": "5HQY9SMBPM9NFS04WQAD172CW4",
"gateway_type": "ppro",
"response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:54Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null
},
"shipping_address": {
"name": "Manuela Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://https://example.ngrok.app/v1/callbacks/097TVNQ4Z08G69J81EQHKKAAPK/conversations.xml"
]
}
],
"redirect_url": "https://example.ngrok.app",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfRms2dkpDMlpvWGNUM0h1d25VZDVuIn19.Jv-pmvBfOXBspPYLzSEwETtgMqOkXqzHPw_J81D_W8uudKSfrIDo5nf80D-WcRWiqduze9xtI7H6WfJLIlwiyQ",
"callback_url": "https://example.ngrok.app",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:34Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfRms2dkpDMlpvWGNUM0h1d25VZDVuIn19.Jv-pmvBfOXBspPYLzSEwETtgMqOkXqzHPw_J81D_W8uudKSfrIDo5nf80D-WcRWiqduze9xtI7H6WfJLIlwiyQ"
},
"redirect_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:54Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null
},
"callback_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-26T13:15:53Z",
"updated_at": "2026-03-26T13:15:54Z",
"status": null
},
"payment_method": {
"token": "01KMN0TTFKY3MNX71442PD2G1H",
"created_at": "2026-03-26T12:10:15.410Z",
"updated_at": "2026-03-26T13:12:48.393Z",
"email": "[email protected]",
"data": null,
"storage_state": "used",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": "2026-03-26T13:12:48.000Z",
"full_name": "Manuela Beyer Rocabado",
"first_name": "Manuela",
"last_name": " Beyer Rocabado",
"bic": null,
"payment_method_type": "oxxo",
"errors": []
}
}
}Refunds
Refunds are only allowed after a successful purchase
Full Refund: Refunds are processed as credit transactions. Oxxo refunds follow standard PPRO refund flow. For full refund just omit the amount from the request body
Partial Refund: You can perform multiple partial refunds until the total equals the actual transaction amount
POST /v1/transactions/{{successful_transaction}}/credit.json{
"transaction": {
"amount": 500, // for full refund just omit the amount parameter.
"currency_code": "MXN",
"gateway_specific_fields": {
"ppro": {
"merchant_refund_id": "my-refund-123",
"refund_bank_name": "Banco Ejemplo",
"refund_bank_agency": "0001",
"refund_account_number": "012345678901234567"
}
},
"notification_url": "https://sajjan.ngrok.app/transaction/#{transaction.token}/callback"
}
}
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:34:49Z",
"updated_at": "2026-03-23T13:34:50Z",
"succeeded": true,
"state": "succeeded",
"token": "81zRVLjpY2LOTFZsKdgY1s3wKsv",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"bic": "BBRUBEBBXXX",
"country": "MX",
"payment_purpose": "Refund"
}
},
"gateway_transaction_id": "1518867500",
"sub_merchant_key": null,
"gateway_latency_ms": 1084,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 1055,
"local_amount": null,
"currency_code": "MXN",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "3J9789KVDW9F0BDZ4YDQFHB4C8",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:34:50Z",
"updated_at": "2026-03-23T13:34:50Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "NKr5KdwGYMCHcGzOV8fzoTZQpcT"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T13:34:49Z",
"updated_at": "2026-03-23T13:34:50Z",
"succeeded": true,
"state": "succeeded",
"token": "81zRVLjpY2LOTFZsKdgY1s3wKsv",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"bic": "BBRUBEBBXXX",
"country": "MX",
"payment_purpose": "Refund"
}
},
"gateway_transaction_id": "1518867500",
"sub_merchant_key": null,
"gateway_latency_ms": 1084,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 500,
"local_amount": null,
"currency_code": "MXN",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "3J9789KVDW9F0BDZ4YDQFHB4C8",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-03-23T13:34:50Z",
"updated_at": "2026-03-23T13:34:50Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "NKr5KdwGYMCHcGzOV8fzoTZQpcT"
}
}P24
P24
Przelewy24 (P24) via PPRO allows merchants to accept payments from Polish consumers via online bank transfers, e-wallets, or installments. The integration supports an offsite purchase flow where the customer is redirected to the P24 payment page to select their bank and complete payment. This document outlines the API requests, required fields, and expected responses for integrating P24 through the PPRO gateway on Spreedly
| Constraints | Value |
|---|---|
| Countries | PL |
| Currencies | EUR, PLN |
| Refund | Full, Partial and Multiple partial |
Create P24 Payment Method
API request
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"payment_method": {
"payment_method_type": "p24",
"full_name": "P24 Name",
"email": "[email protected]",
"country": "PL"
}
}{
"transaction": {
"token": "6JEZH8BMG88NKTD9B6A4KW2N4X",
"created_at": "2026-03-23T06:38:26Z",
"updated_at": "2026-03-23T06:38:26Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KMCPN3KBSVV654644W01AHP1",
"created_at": "2026-03-23T06:38:26.923Z",
"updated_at": "2026-03-23T06:38:26.923Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "PL",
"phone_number": null,
"full_name": "P24 Name",
"first_name": "P24",
"last_name": "Name",
"bic": null,
"payment_method_type": "p24",
"errors": []
}
}
}Create P24 Transaction
API Request
POST /v1/gateways/{{gateway_token}}/purchase.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {
"payment_method_token": "01KMCPN3KBSVV654644W01AHP1",
"amount": 1000,
"currency_code": "EUR",
"redirect_url": "https://example.com/redirect",
"callback_url": "https://example.com/callback",
"retain_on_success": true
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T06:39:28Z",
"updated_at": "2026-03-23T06:39:28Z",
"succeeded": false,
"state": "pending",
"token": "01KMCPN6VQHAXFN3TM9AJQEVDK",
"transaction_type": "OffsitePurchase",
"order_id": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150372457514",
"gateway_latency_ms": 683,
"amount": 1000,
"currency_code": "EUR",
"reference": "150372457514",
"setup_verification": "7NvHbguT9dTilipIOPyhClqsISwr3g5s",
"retain_on_success": true,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "32CXDSEADR9JTTY2S2MMSAT21K",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"pending": true,
"error_code": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9..."
},
"redirect_url": "https://example.com/redirect",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/f?redirection_token=eyJhbGciOiJIUzUxMiJ9...",
"callback_url": "https://example.com/callback",
"attempt_3dsecure": false,
"required_action": "none",
"payment_method": {
"token": "01KMCPN3KBSVV654644W01AHP1",
"email": "[email protected]",
"storage_state": "cached",
"full_name": "P24 Name",
"payment_method_type": "p24",
"errors": []
}
}
}Refund (Credit) P24 Transaction
API Request
POST /v1/transactions/{{transaction_token}}/credit.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {}
}//Status Code: 201 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-23T06:40:17Z",
"updated_at": "2026-03-23T06:40:20Z",
"succeeded": true,
"state": "succeeded",
"token": "01KMCPRFCAYTHV70EW9WGFSMVG",
"transaction_type": "Credit",
"order_id": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"country": "PL"
}
},
"gateway_transaction_id": "1518865158",
"gateway_latency_ms": 3182,
"amount": 1000,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "32CXDSEADR9JTTY2S2MMSAT21K",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"pending": false,
"error_code": null
},
"reference_token": "01KMCPN6VQHAXFN3TM9AJQEVDK"
}
}Webhook Notifications and Status Mapping
PPRO → Spreedly (notification_url)
PPRO sends asynchronous updates to Spreedly at the notification_url configured on the PPRO gateway integration. These notifications include the final status from P24.
Spreedly:
- Receives the PPRO notification.
- Maps the PPRO/P24 status to Spreedly transaction states.
- Updates the original purchase transaction (previously pending)
- Triggers a callback to the merchant's callback_url with the updated status
Spreedly → Merchant (callback_url)
When Spreedly updates the transaction to succeeded or failed, it will POST to the merchant's callback_url with the final transaction state
PIX
PIX
Pix via PPRO allows merchants to accept instant payments from customers in Brazil. Pix is Brazil's instant payment system created by the Central Bank of Brazil (Banco Central do Brasil), launched in November 2020. It enables real-time payments 24/7, 365 days a year. The integration supports offsite purchase flows, where the customer is redirected to complete the Pix payment (typically by scanning a QR code or using their banking app). This document outlines the API requests, required fields, and expected responses for integrating Pix through the PPRO gateway on Spreedly
| Constraints | Value |
|---|---|
| Countries | BR |
| Currencies | BRL |
| Refund | Full, Partial and Multiple partial |
Create PIX Payment Method
API Request
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"payment_method": {
"payment_method_type": "pix",
"full_name": "Full Name",
"email": "[email protected]",
"document_id": "71575743221",
"country": "BR"
}
}{
"transaction": {
"token": "1CGSYVBF809M4R99JG1QVCW1H8",
"created_at": "2026-03-19T07:29:27Z",
"updated_at": "2026-03-19T07:29:27Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KM2FZM1N7T4RVXZ2Q9CNHDJB",
"created_at": "2026-03-19T07:29:27.093Z",
"updated_at": "2026-03-19T07:29:27.093Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "BR",
"phone_number": null,
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"document_id": "71575743221",
"payment_method_type": "pix",
"errors": []
}
}
}Create PIX Transaction
API Request
POST /v1/gateways/{{gateway_token}}/purchase.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {
"payment_method_token": "{{pix_payment_method_token}}",
"amount": 1000,
"currency_code": "BRL",
"redirect_url": "https://example.com/redirect",
"callback_url": "https://example.com/callback"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T07:29:52Z",
"updated_at": "2026-03-19T07:29:53Z",
"succeeded": false,
"state": "pending",
"token": "01KM2G0D28ZS0NA8S3B6710S79",
"transaction_type": "OffsitePurchase",
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150372028369",
"amount": 1000,
"currency_code": "BRL",
"reference": "150372028369",
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "49TBG2JDCZ9PKBVK6HA1T6JS50",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"pending": true,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T07:29:53Z",
"updated_at": "2026-03-19T07:29:53Z",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhb..."
},
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhb...",
"redirect_url": "https://example.com/redirect",
"callback_url": "https://example.com/callback",
"attempt_3dsecure": false,
"required_action": "none",
"payment_method": {
"token": "01KM2FZM1N7T4RVXZ2Q9CNHDJB",
"email": "[email protected]",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"document_id": "71575743221",
"payment_method_type": "pix",
"errors": []
}
}
}Refund (Credit) PIX Transaction
Pix supports full refunds, partial refunds, and multiple partial refunds. Refunds are valid for up to 365 days after the original transaction
API Request
POST /v1/transactions/{{transaction_token}}/credit.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {
"amount": 500 //for partial refund
}
}//Status Code: 201 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T07:45:30Z",
"updated_at": "2026-03-19T07:45:31Z",
"succeeded": true,
"state": "succeeded",
"token": "01KM2GX0EDY8M832PZ7Y270QCY",
"transaction_type": "Credit",
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"bank_code": "00000000",
"bank_name": "Banco do Brasil",
"account_holder": "Full Name"
}
},
"gateway_transaction_id": "1518846369",
"amount": 1000,
"currency_code": "BRL",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "49TBG2JDCZ9PKBVK6HA1T6JS50",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"pending": false,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T07:45:30Z",
"updated_at": "2026-03-19T07:45:31Z"
},
"reference_token": "01KM2GJBMD26WJ8F3VWMM363WN"
}
}Webhook Notifications and Status Mapping
PPRO → Spreedly (notification_url)
- Receives the PPRO notification.
- Maps the PPRO/Pix status to Spreedly transaction states.
- Updates the original purchase transaction (previously pending).
- Triggers a callback to the merchant's callback_url with the updated status.
Spreedly: Receives the PPRO notification.
- Maps the PPRO/Pix status to Spreedly transaction states.
- Updates the original purchase transaction (previously pending).
- Triggers a callback to the merchant's callback_url with the updated status
Spreedly → Merchant (callback_url)
When Spreedly updates the transaction to succeeded or failed, it will POST to the merchant's callback_url with the final transaction state
Sofort
Sofort
| Available country code | AT, BE, CH, DE, ES, GB, IT, NL, PL |
| Refund | Full, Partial, Multiple Partial and Over refund |
Important Note: Transactions may change from any state, especially from FAILED to a SUCCEEDED state at any time.
For further reference go to: Payment Method Integration - Sofort
For information regarding branding, see the Sofort official website.
Trustly
Trustly
Trustly via PPRO allows merchants to accept payments via open banking from customers across Europe. Founded in Sweden in 2008, Trustly operates in 29 countries. The integration supports offsite purchase flows, where the customer is redirected to select their bank, log into online banking, choose an account, and verify the payment. This document outlines the API requests, required fields, and expected responses for integrating Trustly through the PPRO gateway on Spreedly
| Constraints | Value |
|---|---|
| Countries | AT, DE, DK, EE, ES, FI, GB, LT, LV, NL, NO, SE |
| Currencies | DKK, EUR, GBP, NOK, SEK |
| Refund | Full, Partial and Multiple Partial |
Create Trustly Payment Method
API Request
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"payment_method": {
"payment_method_type": "trustly",
"full_name": "Full Name",
"email": "[email protected]",
"country": "DE"
}
}{
"transaction": {
"token": "1CGSYVBF809M4R99JG1QVCW1H8",
"created_at": "2026-03-19T07:29:27Z",
"updated_at": "2026-03-19T07:29:27Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KM2FZM1N7T4RVXZ2Q9CNHDJB",
"created_at": "2026-03-19T07:29:27.093Z",
"updated_at": "2026-03-19T07:29:27.093Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "DE",
"phone_number": null,
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"bic": null,
"payment_method_type": "trustly",
"errors": []
}
}
}Create Trustly Purchase Transaction
API Request
POST /v1/gateways/{{gateway_token}}/purchase.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {
"payment_method_token": "{{trustly_payment_method_token}}",
"amount": 1000,
"currency_code": "EUR",
"redirect_url": "https://example.com/redirect",
"callback_url": "https://example.com/callback",
"gateway_specific_fields": {
"ppro": {
"shopper_reference": "ABCD12345678"
}
}
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T07:29:52Z",
"updated_at": "2026-03-19T07:29:53Z",
"succeeded": false,
"state": "pending",
"token": "01KM2G0D28ZS0NA8S3B6710S79",
"transaction_type": "OffsitePurchase",
"gateway_specific_fields": {
"ppro": {
"shopper_reference": "ABCD12345678"
}
},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150372028369",
"amount": 1000,
"currency_code": "EUR",
"reference": "150372028369",
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "49TBG2JDCZ9PKBVK6HA1T6JS50",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"pending": true,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T07:29:53Z",
"updated_at": "2026-03-19T07:29:53Z",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhb..."
},
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhb...",
"redirect_url": "https://example.com/redirect",
"callback_url": "https://example.com/callback",
"attempt_3dsecure": false,
"required_action": "none",
"payment_method": {
"token": "01KM2FZM1N7T4RVXZ2Q9CNHDJB",
"email": "[email protected]",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"bic": null,
"payment_method_type": "trustly",
"errors": []
}
}
}Refund (Credit) Trustly Transaction
Trustly supports full refunds, partial refunds, and multiple partial refunds. Refunds are valid for up to 365 days after the original transaction
API Request
POST /v1/transactions/{{transaction_token}}/credit.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {}
}//Status Code: 201 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T07:45:30Z",
"updated_at": "2026-03-19T07:45:31Z",
"succeeded": true,
"state": "succeeded",
"token": "01KM2GX0EDY8M832PZ7Y270QCY",
"transaction_type": "Credit",
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"bank_code": "75340090",
"bank_name": "Commerzbank",
"account_holder": "Lisa Pabst"
}
},
"gateway_transaction_id": "1518846369",
"amount": 1000,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "49TBG2JDCZ9PKBVK6HA1T6JS50",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"pending": false,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T07:45:30Z",
"updated_at": "2026-03-19T07:45:31Z"
},
"reference_token": "01KM2GJBMD26WJ8F3VWMM363WN"
}
}Webhook Notifications and Status Mapping
PPRO → Spreedly (notification_url)
PPRO sends asynchronous updates to Spreedly at the notification_url configured on the PPRO gateway integration. These notifications include the final status from Trustly.
Spreedly:
- Receives the PPRO notification.
- Maps the PPRO/Trustly status to Spreedly transaction states.
- Updates the original purchase transaction (previously pending).
- Triggers a callback to the merchant's callback_url with the updated status.
Spreedly → Merchant (callback_url)
When Spreedly updates the transaction to succeeded or failed, it will POST to the merchant’s callback_url with the final transaction state.
SEPA
SEPA
SEPA (Single Euro Payments Area) Direct Debit via PPRO allows merchants to collect Euro-denominated payments from bank accounts across 34 SEPA countries and associated territories. The consumer is redirected to a PPRO-hosted mandate page to enter their IBAN and provide consent, after which the payment is collected via bank debit.
Spreedly integrates SEPA via Model A only — PPRO collects and stores the mandate and generates the pre-notification emails to the consumer
| Constraints | Value |
|---|---|
| Countries | EU: AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE — EEA: IS, LI, NO — Other: AD, SM, MC, VA, CH, GB, GI, GG, IM, JE, and others |
| Currencies | EUR only |
| Refund | Full, partial, and multiple partial |
Create SEPA Payment Method
API Request
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"payment_method": {
"payment_method_type": "sepa_direct_debit", //String;Required;Must be "sepa_direct_debit"
"full_name": "Full Name", //String:Required;Customer's real full name
"email": "[email protected]", //Customer's email address
"country": "DE" //Two-letter ISO country code of the consumer's bank account
}
}{
"transaction": {
"token": "3C0D8VE7478QHT569PG763AAZM",
"created_at": "2026-03-19T10:02:15Z",
"updated_at": "2026-03-19T10:02:15Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KM2RQDQ55CMA1DX3VHYFVRS1", //(string):Unique identifier for payment method
"created_at": "2026-03-19T10:02:15.653Z",
"updated_at": "2026-03-19T10:02:15.653Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"last_successfully_used": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "DE",
"phone_number": null,
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"payment_method_type": "sepa_direct_debit",
"errors": []
}
}
}Create SEPA Transaction
API Request
POST /v1/gateways/{{gateway_token}}/purchase.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {
"payment_method_token": "{{sepa_payment_method_token}}",
"amount": 1000, //Amount in smallest currency unit
"currency_code": "EUR", //Must be "EUR"
"redirect_url": "https://example.com/redirect", //Where to send customer after completing mandate
"callback_url": "https://example.com/callback", //For async settlement status updates from Spreedly
"gateway_specific_fields": {
"ppro": {
"shopper_reference": "ABCD12345678"
}
}
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T10:02:18Z",
"updated_at": "2026-03-19T10:02:19Z",
"succeeded": false,
"state": "pending",
"token": "01KM2RQGCPG454C8NYWJ4GFKSA",
"transaction_type": "OffsitePurchase",
"order_id": null,
"gateway_specific_fields": {
"ppro": {
"shopper_reference": "ABCD12345678"
}
},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150372068662",
"amount": 1000,
"currency_code": "EUR",
"reference": "150372068662",
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "40P2RJS8Z8963AXDKB9QC3E2EM",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"pending": true,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T10:02:19Z",
"updated_at": "2026-03-19T10:02:19Z",
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhb..."
},
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/redirections/forward?redirection_token=eyJhb...",
"redirect_url": "https://example.com/redirect",
"callback_url": "https://example.com/callback",
"attempt_3dsecure": false,
"required_action": "none",
"payment_method": {
"token": "01KM2RQDQ55CMA1DX3VHYFVRS1",
"email": "[email protected]",
"full_name": "Full Name",
"first_name": "Full",
"last_name": "Name",
"payment_method_type": "sepa_direct_debit",
"errors": []
}
}
}Refund (Credit) SEPA Transaction
SEPA supports full refunds, partial refunds, and multiple partial refunds. Refunds are valid for up to 365 days
API Request
POST /v1/transactions/{{transaction_token}}/credit.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {}
}//Status Code: 201 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-03-19T10:04:35Z",
"updated_at": "2026-03-19T10:04:36Z",
"succeeded": true,
"state": "succeeded",
"token": "01KM2RVPER8CC8GA9Q994B0XQ4",
"transaction_type": "Credit",
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"bank_code": "75340090",
"bank_name": "Commerzbank",
"account_holder": "Lisa Pabst"
}
},
"gateway_transaction_id": "1518847042",
"amount": 1000,
"currency_code": "EUR",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "40P2RJS8Z8963AXDKB9QC3E2EM",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"pending": false,
"result_unknown": false,
"error_code": null,
"cancelled": false,
"created_at": "2026-03-19T10:04:36Z",
"updated_at": "2026-03-19T10:04:36Z"
},
"reference_token": "01KM2RQGCPG454C8NYWJ4GFKSA"
}
}Webhook Notifications and Status Mapping
PPRO → Spreedly (notification_url)
PPRO sends asynchronous updates to Spreedly at the notification_url configured on the PPRO gateway integration. These notifications include the final status from SEPA.
Spreedly:
- Receives the PPRO notification.
- Maps the PPRO/SEPA status to Spreedly transaction states.
- Updates the original purchase transaction (previously pending).
- Triggers a callback to the merchant’s callback_url with updated status
Spreedly → Merchant (callback_url)
When Spreedly updates the transaction to succeeded or failed, it will POST to the merchant’s callback_url with the final transaction state
Alipay
Alipay
Alipay via PPRO allows merchants to accept payments from Alipay users. The integration supports offsite purchase flows, where the customer is redirected to Alipay to complete payment. This document outlines the API requests, required fields, and expected responses for integrating Alipay through the PPRO gateway on Spreedly
Create Alipay Payment Method
API Request
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}
{
"payment_method": {
"payment_method_type": "alipay",
"full_name": "Zhang Wei",
"email": "[email protected]",
"country": "CN"
},
"retained": true
}{
"transaction": {
"token": "77664F37MV8HYSXV5WZ3TJ3K7D",
"created_at": "2026-02-26T11:36:48Z",
"updated_at": "2026-02-26T11:36:48Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "8zsmhggEr8wT0CZNHwqdDgnHkAH", //Unique identifier for the payment method
"created_at": "2026-02-26T11:36:48Z",
"updated_at": "2026-02-26T11:36:48Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "CN",
"phone_number": null,
"full_name": "Zhang Wei",
"first_name": "Zhang",
"last_name": "Wei",
"payment_method_type": "alipay",
"errors": []
}
}
}Create Alipay Transaction
API Request
POST/v1/gateways/{{gateway_token}}/purchase.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {
"amount": 1, //Amount in the smallest currency unit
"currency_code": "CNY", //required): "CNY"
"payment_method_token": "{{alipay_payment_method_token}}",
"order_id": "ORDER-123", //Your order reference
"callback_url": "https://example.com/callback", //For async status updates
"redirect_url": "https://example.com/redirect"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-26T11:41:28Z",
"updated_at": "2026-02-26T11:41:34Z",
"succeeded": false,
"state": "pending",
"token": "KVjldHTnV1gEioRuKuklYm8Kr6I", //Unique transaction identifier
"transaction_type": "OffsitePurchase",
"order_id": "ORDER-$",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel"
}
},
"gateway_transaction_id": "150364224369",
"sub_merchant_key": null,
"gateway_latency_ms": 2908,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 1,
"local_amount": null,
"currency_code": "CNY",
"reference": "150364224369",
"setup_verification": "hBQfQDXN3x9YoYzWFrTKw7B3SWe3UBfH",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "23G2CWETK79P09VRH8TBPB4EHP",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-26T11:41:31Z",
"updated_at": "2026-02-26T11:41:34Z",
"status": null,
"checkout_url": "https://mp8tn4c192.execute-api.eu-central-1.amazonaws.com/default/authenticator.html?payment-charge-id=charge_OXsmz5JzF0znJDVxf7yAQ"
},
"shipping_address": {
"name": "Zhang Wei",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"checkout_url": "https://mp8tn4c192.execute-api.eu-central-1.amazonaws.com/default/authenticator.html?payment-charge-id=charge_OXsmz5JzF0znJDVxf7yAQ", //Redirect the customer to this URL to complete payment
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-26T11:41:31Z",
"updated_at": "2026-02-26T11:41:34Z",
"status": null,
"checkout_url": "https://mp8tn4c192.execute-api.eu-central-1.amazonaws.com/default/authenticator.html?payment-charge-id=charge_OXsmz5JzF0znJDVxf7yAQ"
},
"callback_url": null,
"payment_method": {
"token": "8zsmhggEr8wT0CZNHwqdDgnHkAH",
"created_at": "2026-02-26T11:36:48Z",
"updated_at": "2026-02-26T11:36:48Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "Zhang Wei",
"first_name": "Zhang",
"last_name": "Wei",
"payment_method_type": "alipay",
"errors": []
}
}
}Refunds
API Request
POST/v1/transactions/{{transaction_token}}/credit.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"transaction": {}
}//Status Code: 201 Created
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-26T11:48:39Z",
"updated_at": "2026-02-26T11:48:45Z",
"succeeded": true,
"state": "succeeded",
"token": "OZGDYNDpe7UIpO4DyldMWVUpDV3",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {}
},
"gateway_transaction_id": "1518713483",
"sub_merchant_key": null,
"gateway_latency_ms": 3624,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 1,
"local_amount": null,
"currency_code": "CNY",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "23G2CWETK79P09VRH8TBPB4EHP",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-26T11:48:43Z",
"updated_at": "2026-02-26T11:48:45Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "KVjldHTnV1gEioRuKuklYm8Kr6I"
}
}Webhook Notifications and Status Mapping
PPRO -> Spreedly (notification_url)
PPRO sends asynchronous updates to Spreedly at the notification_url configured on the PPRO gateway integration. These notifications include the final status from Alipay.
Spreedly:
- Receives the PPRO notification.
- Maps the PPRO/Alipay status to Spreedly transaction states.
- Updates the original purchase transaction (previously pending).
- Triggers a callback to the merchant’s callback_url with updated status.
Spreedly → Merchant (callback_url)
When Spreedly updates the transaction to succeeded or failed, it will POST to the merchant’s callback_url with the final transaction state.
WeChatPay
WeChatPay
WeChat Pay via PPRO allows merchants to accept payments from WeChat Pay users through a single API integration. The merchant sends a transaction request to PPRO, which returns a QR code or redirect URL for the customer to complete payment in the WeChat app. The payment status is then confirmed asynchronously via webhook notification. Transactions are typically made in CNY for consumers, with settlement currency depending on the merchant setup.
WeChatPay Purchase Method
API Request
POST/v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{payment_method_token}}",
"amount": 1150,
"currency_code": "CNY",
"redirect_url": "{{redirect_url}}",
"callback_url": "{{callback_url}}",
"order_id": "J2wkc3cdDaJS"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-27T09:09:03Z",
"updated_at": "2026-02-27T09:09:04Z",
"succeeded": false,
"state": "pending", //pending immediately after the purchase
"token": "01KJF5QMR5TE66BDFGSAD1DV3Q",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"payment_purpose": "5PQK5L2 SPREEDLYTEST",
"qr_code_url": "weixin://wxpay/bizpayurl?pr=abcdefg",
"expiry_timestamp": "1772190544",
"src_amount": "1500",
"src_currency": "CNY",
"settlement_currency": "EUR",
"settlement_amount": "191",
"fx_rate": "7.843417"
}
},
"gateway_transaction_id": "2390598937",
"sub_merchant_key": null,
"gateway_latency_ms": 511,
"warning": null,
"application_id": null,
"risk_data": {},
"merchant_metadata": {},
"customer_data": {},
"order_data": {},
"workflow_key": null,
"protection_parameters": {},
"amount": 1500,
"local_amount": null,
"currency_code": "CNY",
"reference": "2390598937",
"setup_verification": "dyDXr8Ti2JzOxBO0e46ksb1rxgkeH07t",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "6YHTC8XXZW8RRTSMQP9DY3P17A",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:09:04Z",
"updated_at": "2026-02-27T09:09:04Z",
"status": null,
"checkout_url": "https://r2.girogate.de/wechatpay/S1067/I?tx=2390598937&rs=LZknufOejEf5lz8O0SFxodHodDR2Jhdc&cs=109f5b98894e4caeff7cc70c9e67e27a24cec7f9f63c0aa004edcf1ec10c16a2"
},
"shipping_address": {
"name": "John Doe",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"checkout_url": "https://r2.girogate.de/wechatpay/S1067/I?tx=2390598937&rs=LZknufOejEf5lz8O0SFxodHodDR2Jhdc&cs=109f5b98894e4caeff7cc70c9e67e27a24cec7f9f63c0aa004edcf1ec10c16a2",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:09:04Z",
"updated_at": "2026-02-27T09:09:04Z",
"status": null,
"checkout_url": "https://r2.girogate.de/wechatpay/S1067/I?tx=2390598937&rs=LZknufOejEf5lz8O0SFxodHodDR2Jhdc&cs=109f5b98894e4caeff7cc70c9e67e27a24cec7f9f63c0aa004edcf1ec10c16a2" //where you must redirect the customer to complete the wechatpay payment
},
"callback_url": null,
"payment_method": {
"token": "01KJF4AJJ558VX4NF16G576C7X",
"created_at": "2026-02-27T08:44:27.077Z",
"updated_at": "2026-02-27T08:44:27.077Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"bic": null,
"payment_method_type": "wechat_pay",
"errors": []
}
}
}//Successful Response (Purchase – success after webhook)
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-27T09:09:03Z",
"updated_at": "2026-02-27T09:18:09Z",
"succeeded": true,
"state": "succeeded",
"token": "01KJF5QMR5TE66BDFGSAD1DV3Q",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"payment_purpose": "5PQK5L2 SPREEDLYTEST",
"qr_code_url": "weixin://wxpay/bizpayurl?pr=abcdefg",
"expiry_timestamp": "1772190544",
"src_amount": "1500",
"src_currency": "CNY",
"settlement_currency": "EUR",
"settlement_amount": "191",
"fx_rate": "7.843417"
}
},
"gateway_transaction_id": "2390598937",
"sub_merchant_key": null,
"gateway_latency_ms": 327,
"warning": "Unable to perform a redirect because no redirect_url was provided.",
"application_id": null,
"risk_data": {},
"merchant_metadata": {},
"customer_data": {},
"order_data": {},
"workflow_key": null,
"protection_parameters": {},
"amount": 1500,
"local_amount": null,
"currency_code": "CNY",
"reference": "2390598937",
"setup_verification": "dyDXr8Ti2JzOxBO0e46ksb1rxgkeH07t",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6YHTC8XXZW8RRTSMQP9DY3P17A",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:18:06Z",
"updated_at": "2026-02-27T09:18:06Z",
"status": null
},
"shipping_address": {
"name": "John Doe",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"checkout_url": "https://r2.girogate.de/wechatpay/S1067/I?tx=2390598937&rs=LZknufOejEf5lz8O0SFxodHodDR2Jhdc&cs=109f5b98894e4caeff7cc70c9e67e27a24cec7f9f63c0aa004edcf1ec10c16a2",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:09:04Z",
"updated_at": "2026-02-27T09:09:04Z",
"status": null,
"checkout_url": "https://r2.girogate.de/wechatpay/S1067/I?tx=2390598937&rs=LZknufOejEf5lz8O0SFxodHodDR2Jhdc&cs=109f5b98894e4caeff7cc70c9e67e27a24cec7f9f63c0aa004edcf1ec10c16a2"
},
"callback_url": null,
"callback_response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:18:06Z",
"updated_at": "2026-02-27T09:18:06Z",
"status": null
},
"payment_method": {
"token": "01KJF4AJJ558VX4NF16G576C7X",
"created_at": "2026-02-27T08:44:27.077Z",
"updated_at": "2026-02-27T08:44:27.077Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"bic": null,
"payment_method_type": "wechat_pay",
"errors": []
}
}
}//Declined Response (Purchase – User Declined)
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-27T09:21:42Z",
"updated_at": "2026-02-27T09:24:29Z",
"succeeded": false,
"state": "gateway_processing_failed",
"token": "01KJF6ESDZZ1M2CWV9CFGY8KGF",
"transaction_type": "OffsitePurchase",
"order_id": "J2wkc3cdDaJS",
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "NOT_EXPECTED",
"channel": "testchannel",
"payment_purpose": "50F45E4 SPREEDLYTEST",
"qr_code_url": "weixin://wxpay/bizpayurl?pr=abcdefg",
"expiry_timestamp": "1772191302",
"src_amount": "9804",
"src_currency": "CNY",
"settlement_currency": "EUR",
"settlement_amount": "1250",
"fx_rate": "7.843417",
"fail_reason": "USER_ABORT"
}
},
"gateway_transaction_id": "2390599023",
"sub_merchant_key": null,
"gateway_latency_ms": 330,
"warning": null,
"application_id": null,
"risk_data": {},
"merchant_metadata": {},
"customer_data": {},
"order_data": {},
"workflow_key": null,
"protection_parameters": {},
"amount": 1250,
"local_amount": null,
"currency_code": "EUR",
"reference": "2390599023",
"setup_verification": "sME5k3l0050Pl0GjbogU5x3EmFrFEEGP",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message": "The payment was cancelled.",
"gateway_token": "6YHTC8XXZW8RRTSMQP9DY3P17A",
"gateway_type": "ppro",
"response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:24:29Z",
"updated_at": "2026-02-27T09:24:29Z",
"status": null
},
"shipping_address": {
"name": "John Doe",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://core.spreedly.com/v1/callbacks/43GE6MFR6M815B8N03CHV2NCXN/conversations.xml"
]
}
],
"redirect_url": "http://www.example.com/redirect",
"checkout_url": "https://r2.girogate.de/wechatpay/S1067/I?tx=2390599023&rs=2Z8B59QlV7VjlQRlnjavqjSGHloAiMeW&cs=878525690ad1f379b39f499f90aa73e9342eff9e1ad7e7cdbe4100a6c5d6bc39",
"callback_url": "http://www.example.com/redirect",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null, //"USER_ABORT" occurs when the user aborts the payment after visiting the checkout_url page. You will receive a webhook for the status update
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:21:42Z",
"updated_at": "2026-02-27T09:21:42Z",
"status": null,
"checkout_url": "https://r2.girogate.de/wechatpay/S1067/I?tx=2390599023&rs=2Z8B59QlV7VjlQRlnjavqjSGHloAiMeW&cs=878525690ad1f379b39f499f90aa73e9342eff9e1ad7e7cdbe4100a6c5d6bc39"
},
"callback_response": {
"success": false,
"message": "The payment was cancelled.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "USER_ABORT",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:24:29Z",
"updated_at": "2026-02-27T09:24:29Z",
"status": null
},
"payment_method": {
"token": "01KJF4AJJ558VX4NF16G576C7X",
"created_at": "2026-02-27T08:44:27.077Z",
"updated_at": "2026-02-27T09:18:06.783Z",
"email": null,
"data": null,
"storage_state": "used",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"bic": null,
"payment_method_type": "wechat_pay",
"errors": []
}
}
}Refunds
Refunds are only allowed after a successful purchase
Full Refund after Purchase
POST/v1/transactions/{successful_transaction}/credit.json{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-17T08:33:30Z",{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-27T09:34:37Z",
"updated_at": "2026-02-27T09:34:38Z",
"succeeded": true,
"state": "succeeded",
"token": "01KJF76EF6JVYSW6KDHC1H2MVB",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {}
},
"gateway_transaction_id": "1321290646",
"sub_merchant_key": null,
"gateway_latency_ms": 716,
"warning": null,
"application_id": null,
"risk_data": {},
"merchant_metadata": {},
"customer_data": {},
"order_data": {},
"workflow_key": null,
"amount": 1500,
"local_amount": null,
"currency_code": "CNY",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6YHTC8XXZW8RRTSMQP9DY3P17A",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:34:38Z",
"updated_at": "2026-02-27T09:34:38Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "01KJF5QMR5TE66BDFGSAD1DV3Q"
}
}
"updated_at": "2026-02-17T08:33:36Z",
"succeeded": true,
"state": "succeeded",
"token": "NmCpHnGpoJCXkE1O2nCpW7XAFaD",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"d_local": {
"notification_url": "http://core.spreedly.test/transaction/NmCpHnGpoJCXkE1O2nCpW7XAFaD/callback",
"status": "SUCCESS"
}
},
"gateway_transaction_id": "REF-15104-x1kp89ut-928a083mhd7dp3-gv7118iit8n4",
"sub_merchant_key": null,
"gateway_latency_ms": 3411,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"amount": 5200,
"local_amount": 52,
"currency_code": "BRL",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "10J6ERFCQM82SVSF78AA3TT053",
"gateway_type": "d_local",
"response": {
"success": true,
"message": "The refund was paid.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-17T08:33:33Z",
"updated_at": "2026-02-17T08:33:36Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "Z3vLrvLQBo0mnMNOhGiGdQb1Z91"
}
}
Partial Refund
Multiple partial refunds can be performed until the total equals the actual transaction amount
{
"transaction": {
"amount": 700
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-02-27T09:41:19Z",
"updated_at": "2026-02-27T09:41:19Z",
"succeeded": true,
"state": "succeeded",
"token": "01KJF7JPPS8DSDV3XMXASPQCC7",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {
"ppro": {}
},
"gateway_transaction_id": "1321290660",
"sub_merchant_key": null,
"gateway_latency_ms": 652,
"warning": null,
"application_id": null,
"risk_data": {},
"merchant_metadata": {},
"customer_data": {},
"order_data": {},
"workflow_key": null,
"amount": 700,
"local_amount": null,
"currency_code": "CNY",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6YHTC8XXZW8RRTSMQP9DY3P17A",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-02-27T09:41:19Z",
"updated_at": "2026-02-27T09:41:19Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "01KJF7G211BY4G7X5802GDM3XB"
}
}Bancontact (Wallet Initiated Payments)
Bancontact (WIP)
Bancontact Wallet Initiated Payments (WIP) allows initiation by the merchant or the consumer of a card-not-present payment transaction without performing Strong Customer Authentication after previous enrollment of the Bancontact Card. That enables the customers to offer one-click payment flows and the customers/merchants to initiate recurrent payment flows.
Create Bancontact WIP Payment Method
API Request
POST /v1/payment_methods.jsonContent-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
Password {{access_secret}}{
"payment_method": {
"payment_method_type": "bancontact_wip", //Must be "bancontact_wip
"country_code": "BE",
"full_name": "John Doe"
}
}//Status Code: 201 Created
{
"transaction": {
"token": "7QNQ0K0JZW9CGBKHXMM0KCP9HG",
"created_at": "2026-01-21T10:18:30Z",
"updated_at": "2026-01-21T10:18:30Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "IGI5wFoN9m8zvKi848xI2Sepvgn", //Unique identifier for the payment method
"created_at": "2026-01-21T10:18:30Z",
"updated_at": "2026-01-21T10:18:30Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "BE",
"phone_number": null,
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "bancontact_wip",
"errors": []
}
}
}Create Agreement and Initial Transaction
During the initial consumer-initiated transaction, merchants are required to create a payment agreement. PPRO will securely store the consumer's card details as part of this agreement, and SCA will be needed. For subsequent transactions, the merchant simply needs to provide the agreement ID as input for WIP transactions
Gateway Specific Fields
Required GSF
agreement_amount:The amount to wire in the currency’s smallest representable unit as per ISO4217. Example: For EUR 0.01, the amount is 1. For EUR 1.00, the amount is 100.initiation:consumer or merchant
Optional GSF
amount_type:If value is EXACT, then subsequent transaction amounts must match the amount specified in the agreement. If MAX, any amount beneath the agreed amount is supported. Defaults to MAX.start_date:The earliest date after which the consumer agrees to be charged. Defaults to the agreement creation date.end_date :The last date you can charge the consumer under this agreement.frequency_interval:A number describing the interval between payments. Example: if the value is 2 and frequencyType is WEEKLY, then it means the consumer agrees to be charged every 2 weeks. Defaults to 1.frequency_type:DAILY/WEEKLY/MONTHLY/YEARLY (required if frequency_interval set)merchant_agreement_id:Identifier on merchant side. Any string value
"gateway_specific_fields": {
"ppro": {
"initiation": "consumer",
"amount_type": "EXACT", //[MAX, EXACT] 2 values allowed
"start_date": "2026-01-21T18:23:47.123Z",
"end_date": "2026-05-21T11:23:47.123Z",
"frequency_interval": 1,
"frequency_type": "MONTHLY",
"merchant_agreement_id": "test123456",
"agreement_amount": 5000
}
}API Request
POST /v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{bancontact_wip_payment_method_token}}",
"amount": 5000,
"currency_code": "EUR",
"callback_url": "https://example.com",
"redirect_url": "https://example.com",
"gateway_specific_fields": {
"ppro": {
"initiation": "consumer",
"agreement_amount": 5000,
"amount_type": "EXACT", //[MAX, EXACT] 2 values allowed
"start_date": "2026-01-21T18:23:47.123Z",
"end_date": "2026-05-21T11:23:47.123Z",
"frequency_interval": 1,
"frequency_type": "MONTHLY",
"merchant_agreement_id": "test123456"
}
}
}
}//Status Code: 202 Accepted
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-01-21T10:33:35Z",
"updated_at": "2026-01-21T10:33:36Z",
"succeeded": false,
"state": "pending",
"token": "YcXSnc5hG3whTpmTQyoDo5VfDk7",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {
"ppro": {
"initiation": "consumer",
"amount_type": "EXACT",
"start_date": "2026-01-21T18:23:47.123Z",
"end_date": "2026-05-21T11:23:47.123Z",
"frequency_interval": 1,
"frequency_type": "MONTHLY",
"merchant_agreement_id": "test123456",
"agreement_amount": 5000
}
},
"gateway_specific_response_fields": {
"ppro": {
"channel": "testchannel",
"agreement_id": "1000015274",
"agreement_merchant_id": "test123456",
"agreement_initial_transaction_id": "150350766523"
}
},
"gateway_transaction_id": "150350766523",
"sub_merchant_key": null,
"gateway_latency_ms": 1073,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 2500,
"local_amount": null,
"currency_code": "EUR",
"reference": "150350766523",
"setup_verification": "J3G9jcEYbaKxVWG95F06NVoswrgzfkHf",
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "2G0H96ZE3F9TNBSK3J9QPZ77QY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-01-21T10:33:36Z",
"updated_at": "2026-01-21T10:33:36Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJhZ3JfeTVJTFBhMVR0MHU5WlNtcHZCMVpjIiwicyI6Imh0dHA6Ly9jb3JlLnNwcmVlZGx5LnRlc3QvdHJhbnNhY3Rpb24vWWNYU25jNWhHM3doVHBtVFF5b0RvNVZmRGs3L3JlZGlyZWN0P2FncmVlbWVudGlkPTEwMDAwMTUyNzQmY3M9YjU3YjRmYzk3ODdmNjk3MmIwODUwMDc4NzVmYmZjYzU4ZTI5MjlhOGRmNWY0NTI3OWY2MGUxZjJlNGIyOGE0NCZtYWdyZWVtZW50aWQ9dGVzdDEyMzQ1NiIsImYiOiJodHRwOi8vY29yZS5zcHJlZWRseS50ZXN0L3RyYW5zYWN0aW9uL1ljWFNuYzVoRzN3aFRwbVRReW9EbzVWZkRrNy9yZWRpcmVjdD9hZ3JlZW1lbnRpZD0xMDAwMDE1Mjc0JmNzPWI1N2I0ZmM5Nzg3ZjY5NzJiMDg1MDA3ODc1ZmJmY2M1OGUyOTI5YThkZjVmNDUyNzlmNjBlMWYyZTRiMjhhNDQmbWFncmVlbWVudGlkPXRlc3QxMjM0NTYmaXNGYWlsdXJlPXRydWUiLCJtIjoiMTA3MzY3In19.ok6uzffO2ITv3KWjvHqPqF44uSjUxl9mKuJwd31Xp3qhh6Mon_zILczN4cIsOM-TVfKLV6WIrzJtytvRPB9wTg"
},
"shipping_address": {
"name": "John Doe",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJhZ3JfeTVJTFBhMVR0MHU5WlNtcHZCMVpjIiwicyI6Imh0dHA6Ly9jb3JlLnNwcmVlZGx5LnRlc3QvdHJhbnNhY3Rpb24vWWNYU25jNWhHM3doVHBtVFF5b0RvNVZmRGs3L3JlZGlyZWN0P2FncmVlbWVudGlkPTEwMDAwMTUyNzQmY3M9YjU3YjRmYzk3ODdmNjk3MmIwODUwMDc4NzVmYmZjYzU4ZTI5MjlhOGRmNWY0NTI3OWY2MGUxZjJlNGIyOGE0NCZtYWdyZWVtZW50aWQ9dGVzdDEyMzQ1NiIsImYiOiJodHRwOi8vY29yZS5zcHJlZWRseS50ZXN0L3RyYW5zYWN0aW9uL1ljWFNuYzVoRzN3aFRwbVRReW9EbzVWZkRrNy9yZWRpcmVjdD9hZ3JlZW1lbnRpZD0xMDAwMDE1Mjc0JmNzPWI1N2I0ZmM5Nzg3ZjY5NzJiMDg1MDA3ODc1ZmJmY2M1OGUyOTI5YThkZjVmNDUyNzlmNjBlMWYyZTRiMjhhNDQmbWFncmVlbWVudGlkPXRlc3QxMjM0NTYmaXNGYWlsdXJlPXRydWUiLCJtIjoiMTA3MzY3In19.ok6uzffO2ITv3KWjvHqPqF44uSjUxl9mKuJwd31Xp3qhh6Mon_zILczN4cIsOM-TVfKLV6WIrzJtytvRPB9wTg",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "PENDING",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": true,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-01-21T10:33:36Z",
"updated_at": "2026-01-21T10:33:36Z",
"status": null,
"checkout_url": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJhZ3JfeTVJTFBhMVR0MHU5WlNtcHZCMVpjIiwicyI6Imh0dHA6Ly9jb3JlLnNwcmVlZGx5LnRlc3QvdHJhbnNhY3Rpb24vWWNYU25jNWhHM3doVHBtVFF5b0RvNVZmRGs3L3JlZGlyZWN0P2FncmVlbWVudGlkPTEwMDAwMTUyNzQmY3M9YjU3YjRmYzk3ODdmNjk3MmIwODUwMDc4NzVmYmZjYzU4ZTI5MjlhOGRmNWY0NTI3OWY2MGUxZjJlNGIyOGE0NCZtYWdyZWVtZW50aWQ9dGVzdDEyMzQ1NiIsImYiOiJodHRwOi8vY29yZS5zcHJlZWRseS50ZXN0L3RyYW5zYWN0aW9uL1ljWFNuYzVoRzN3aFRwbVRReW9EbzVWZkRrNy9yZWRpcmVjdD9hZ3JlZW1lbnRpZD0xMDAwMDE1Mjc0JmNzPWI1N2I0ZmM5Nzg3ZjY5NzJiMDg1MDA3ODc1ZmJmY2M1OGUyOTI5YThkZjVmNDUyNzlmNjBlMWYyZTRiMjhhNDQmbWFncmVlbWVudGlkPXRlc3QxMjM0NTYmaXNGYWlsdXJlPXRydWUiLCJtIjoiMTA3MzY3In19.ok6uzffO2ITv3KWjvHqPqF44uSjUxl9mKuJwd31Xp3qhh6Mon_zILczN4cIsOM-TVfKLV6WIrzJtytvRPB9wTg"
},
"callback_url": null,
"payment_method": {
"token": "IGI5wFoN9m8zvKi848xI2Sepvgn",
"created_at": "2026-01-21T10:18:30Z",
"updated_at": "2026-01-21T10:18:30Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "bancontact_wip",
"errors": []
}
}
}Transaction Note
The transaction remains pending until the customer completes the authentication. The authentication flow for Bancontact WIP first transaction attempt is very similar to Bancontact, also including a Hosted Payment Page (HPP) redirect for initial customer initiated transactions + Scan QR Code or App Intent or 3DS.
PPRO will send 2 transaction status change notifications
Bancontact transactions follow a two-step process in which PPRO first performs an authorization, followed by a capture of the transaction with Bancontact.
This process runs seamlessly in the background, but you will receive two separate webhook notifications—one for each step. In both cases, the transaction status retrieved via the GETTXSTATUS call will be SUCCEEDED
Webhook Notifications
The gateways posts asynchronous updates to the Spreedly notification_url. After, we have update the transaction we will post updates to the callback_url.
Response Fields:
transaction -> token (string): Unique identifier for the transaction
Gateway Specific Response Fields:
agreement_id (string): Agreement ID returned from PPRO
Create subsequent transactions using Agreement ID
The request structure is the same as a TRANSACTION call input for the payment method in question, plus this added AGREEMENT_ID field and by using INITIATION=MERCHANT when initializing the transaction. In the TRANSACTION call output, you should see that the recurring payment succeeds immediately without the need to redirect / authenticate the consumer.
Gateway Specific Fields
agreement_id: agreement Id returned in gateway_specific_response_fields of previous request.
initiation: consumer or merchant
"gateway_specific_fields": {
"ppro": {
"agreement_id": "1000015265",
"initiation": "merchant"
}
}API Request
POST /v1/gateways/{{gateway_token}}/purchase.json{
"transaction": {
"payment_method_token": "{{bancontact_wip_payment_method_token}}",
"amount": 5000,
"currency_code": "EUR",
"callback_url": "https://example.com",
"redirect_url": "https://example.com",
"gateway_specific_fields": {
"ppro": {
"agreement_id": "1000015265",
"initiation": "merchant"
}
}
}
}//Status Code: 202 Accepted
{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-01-21T10:50:06Z",
"updated_at": "2026-01-21T10:50:07Z",
"succeeded": false,
"state": "pending",
"token": "FjAW9OuDhHjtmv4r5i5dRlzOLmA",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {
"ppro": {
"agreement_id": "1000015274",
"initiation": "merchant"
}
},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "WAITING",
"channel": "testchannel",
"card_expiry": "3103",
"card_masked_pan": "41111111XXXXXX1111",
"card_bin": "41111111",
"last_four": "1111"
}
},
"gateway_transaction_id": "150350774668",
"sub_merchant_key": null,
"gateway_latency_ms": 1122,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"amount": 5000,
"local_amount": null,
"currency_code": "EUR",
"reference": "150350774668",
"setup_verification": null,
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_pending",
"message": "Pending",
"gateway_token": "2G0H96ZE3F9TNBSK3J9QPZ77QY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "SUCCEEDED",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-01-21T10:50:07Z",
"updated_at": "2026-01-21T10:50:07Z",
"status": null
},
"shipping_address": {
"name": "John Doe",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"callback_url": null,
"payment_method": {
"token": "IGI5wFoN9m8zvKi848xI2Sepvgn",
"created_at": "2026-01-21T10:18:30Z",
"updated_at": "2026-01-21T10:18:30Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "bancontact_wip",
"errors": []
}
}
}Enquire API
PATCH /v1/transactions/{{transaction_token}}{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-01-21T10:50:06Z",
"updated_at": "2026-01-21T10:53:19Z",
"succeeded": true,
"state": "succeeded",
"token": "FjAW9OuDhHjtmv4r5i5dRlzOLmA",
"transaction_type": "OffsitePurchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {
"ppro": {
"agreement_id": "1000015274",
"initiation": "merchant"
}
},
"gateway_specific_response_fields": {
"ppro": {
"fund_status": "WAITING",
"channel": "testchannel",
"card_expiry": "3103",
"card_masked_pan": "41111111XXXXXX1111",
"card_bin": "41111111",
"last_four": "1111"
}
},
"gateway_transaction_id": "150350774668",
"sub_merchant_key": null,
"gateway_latency_ms": 1122,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"protection_parameters": null,
"original_transaction_updated": true,
"amount": 5000,
"local_amount": null,
"currency_code": "EUR",
"reference": "150350774668",
"setup_verification": null,
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "2G0H96ZE3F9TNBSK3J9QPZ77QY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "The payment was successfully completed.",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-01-21T10:53:18Z",
"updated_at": "2026-01-21T10:53:19Z",
"status": null
},
"shipping_address": {
"name": "John Doe",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"callback_url": null,
"payment_method": {
"token": "IGI5wFoN9m8zvKi848xI2Sepvgn",
"created_at": "2026-01-21T10:18:30Z",
"updated_at": "2026-01-21T10:18:30Z",
"email": null,
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"payment_method_type": "bancontact_wip",
"errors": []
}
}
}Cancel an agreement
API Request
POST /v1/transactions/{{transaction}}/void.json{
"transaction": {
"on_test_gateway": true,
"created_at": "2026-01-21T11:01:03Z",
"updated_at": "2026-01-21T11:01:04Z",
"succeeded": true,
"state": "succeeded",
"token": "Jlh6pbH3IiOS1MGEm9lQK57YzhU",
"transaction_type": "Void",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"merchant_profile_key": null,
"gateway_specific_fields": {
"ppro": {
"agreement_id": "1000015199"
}
},
"gateway_specific_response_fields": {
"ppro": {
"channel": "testchannel",
"agreement_id": "1000015274",
"agreement_merchant_id": "test123456",
"agreement_initial_transaction_id": "150350766523"
}
},
"gateway_transaction_id": "150350766523",
"sub_merchant_key": null,
"gateway_latency_ms": 982,
"warning": null,
"application_id": null,
"risk_data": null,
"merchant_metadata": null,
"customer_data": null,
"order_data": null,
"workflow_key": null,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "2G0H96ZE3F9TNBSK3J9QPZ77QY",
"gateway_type": "ppro",
"response": {
"success": true,
"message": "REVOKED_BY_MERCHANT",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": null,
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2026-01-21T11:01:04Z",
"updated_at": "2026-01-21T11:01:04Z",
"status": null
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "YcXSnc5hG3whTpmTQyoDo5VfDk7"
}
}Updated 9 days ago