PayPaga

PayPaga Integration alternatives are as follows:

Payment Widget Integration

Coming soon.

Direct API Integration

The Direct API integrations allows full control over the flow and interactions with the consumer.

API requests are secured with OAuth2.0 authorisation.

PayURL Integration

This provides a web funnel solution for pay-ins to be integrated as part of the merchants' checkout experience.

undefined

Standards that define the possible values for common data types used in all APIs.
Country

ISO 3166-1 Alpha 2 is the standard used for country codes, see ISO 3166-1 Alpha-2 codes for further reference

Currency

ISO 4217 alphabetic code is the standard used for currency codes, see ISO 4217 for further reference

An advanced workflow designed for customised integrations where the merchant will manage the complete consumer experience leveraging a backend integration for the transaction processing. The workflow steps are listed below and illustrated in the sequence diagram.

Prior to any transaction processing the Merchant must configure a Notification Method in the Developer's section of the Merchant Portal for the corresponding environment to enable transaction lifecycles notifications.
Call OAuth2.0 Token Generation and retrieve OAuth2.0 token
Using the OAuth2.0 token, the Merchant will interact with PayPaga API in two steps per transaction as follows:
1. Call the Pay In Payment Options request to retrieve the current selection of orchestrated Payment Methods with corresponding data requirements
2. Call the Pay In Payment Processing request with selected Payment Method, supplying any Payment Method specific data
Action payment lifecycle notifications sent to the registered notification method.

Execute Pay Out transactions.

The PayPaga PayURL is a customized checkout webpage to allow the selection of a payment method, entering any required information and submitting the payment.

The workflow steps are listed below:

Call OAuth2.0 Token Generation and retrieve OAuth2.0 token.
Using the OAuth2.0 token, call the Get PayURL endpoint to get a new PayPaga PayURL based on the parameters provided in the request.
Redirect the user to the generated PayPaga PayURL.
The PayPaga PayURL will present to the user a list of payment methods previously approved by the merchant for the specified country.
Then, the user selects their preferred payment method, enters any required information and submits the payment.
Upon successful submission, the payment result is displayed, including instructions for asynchronous payments. A new transaction with status of PENDING will be created in the system.

This service initiates the PayPaga PayURL flow where, if successful, returns a new PayURL to the user to be redirected to for payment completion.

Sandbox: https://merchant-api.stg.paypaga.com/payurl

Production: https://merchant-api.paypaga.com/payurl

Header Parameters

Authorizationstring Required

OAuth2.0 Bearer token returned from OAuth2.0 Token Generation API call

Body Parameters

merchant_idstring (uuid)Required

Merchant identifier provided in the Developer's section of the merchant portal

country_codestring Required

ISO 3166-1 Alpha 2 Country code where the transaction is being processed

currencystring Required

ISO 4217 alphabetic currency code of the transaction amount (e.g. MXN, BRL, etc.).

transaction_totalnumber Required

Total amount of the transaction, including fees and taxes, expressed as a decimal amount in the currency major and minor units

merchant_transaction_referencestring Required

Merchant supplied unique transaction identifier for correlation

Min length

2

Max length

45

Pattern

^[A-Za-z0-9-_]+

Response

200

Object

Success Response

Response Attributes

transaction_idstring (uuid)

Unique PayPaga assigned transaction identifier to be used in the transaction lifecycle

transaction_datestring (date)

The UTC time zone transaction date in the PayPaga system

Pattern

YYYY-MM-DD

merchant_idstring (uuid)

Unique Merchant identifier supplied in the request

payurl_idstring (uuid)

Unique identifier assigned to PayURL for the transaction

messagestring

Response status description

versionstring

API Version for support purposes

pay_urlstring (uri)

PayURL checkout webpage with the corresponding payurl_id as a query string parameter. The user must be redirected to this URL to complete the payment

400

Object

Validation Error Response

Response Attributes

transaction_idstring (uuid)

Unique PayPaga assigned transaction identifier to be used in the transaction lifecycle

datetimestring (date-time)

Transaction processing timestamp (UTC time zone)

Pattern

YYYY-MM-DD hh:mm:ss.sss

error_codenumber (int32)

Numeric error code

Enum values:

100

Field validation error

108

The configuration is not available for this merchant

110

Transaction amount is out of range

116

Invalid decimals, only 2 decimal places are allowed

152

The payment method is not valid or not available for the merchant

153

The transaction amount must be lower than nnnnn

500

Unexpected error

messagestring

Response status description

versionstring

API Version for support purposes

400 with error_details

Object

Numeric error code.

Response Attributes

transaction_idstring

Unique PayPaga assigned transaction identifier to be used in the transaction lifecycle

datetimestring (date-time)

The UTC time zone transaction date in the PayPaga system.

Pattern

YYYY-MM-DD hh:mm:ss.sss

error_codenumber (int32)

Numeric error code.

Enum values:

100

Field validation error

108

The configuration is not available for this merchant

110

Transaction amount is out of range

116

Invalid decimals, only 2 decimal places are allowed

152

The payment method is not valid or not available for the merchant

153

The transaction amount must be lower than nnnnn

500

Unexpected error

error_detailsarray

Groups all validation errors found in the request.

Show child attributes

messagestring

Response status description

versionstring

API Version for support purposes

curl --location 'https://merchant-api.paypaga.com/payurl' \
--header 'Authorization: [OAUTH2.0-TOKEN]' \
--data '{
  "merchant_id": "00aa0bb0-0000-0000-00cc-0000dd0eee00",
  "country_code": "MX",
  "currency": "MXN",
  "transaction_total": 10.26,
  "merchant_transaction_reference": "custom-reference-123456"
}'

{
  "transaction_id": "20240902-2222-3333-cccc-555555aa55a5",
  "transaction_date": "2024-09-02",
  "merchant_id": "00aa0bb0-0000-0000-00cc-0000dd0eee00",
  "payurl_id": "330004d4-a55a-4b44-cc55-d2dddd2ddd22",
  "message": "PayURL Created successfully",
  "version": "0.1",
  "pay_url": "https://payurl.dev.paypaga.com/payment?payurl_id=330004d4-a55a-4b44-cc55-d2dddd2ddd22"
}

It is possible to narrow down the list of payment options the user can choose from, by using the parameter “payment_method_codes” as follows:

These are the possible scenarios:

If the list contains an invalid method, an error will occur and no PayURL will be generated.
If the list contains valid methods, the PayURL web page will show only those as payment options.
If the list contains a single valid option and that option requires additional information to be entered by the user, the PayURL will show the correspondent fields to enter that information.
If the list contains a single valid option and that option doesn’t require any additional information, the PayURL won´t display the payment options step. Instead, the payment request will be submitted automatically using the pre-selected payment option and the payment result will be displayed, including instructions for asynchronous payments.
If customer data is required to continue with a specific payment method, it can also be pre-emptively provided in the request.

Header Parameters

Authorizationstring

OAuth2.0 Bearer token returned from OAuth2.0 Token Generation API call

Body Parameters

merchant_idstring (uuid)

Merchant identifier provided in the Developer's section of the merchant portal

country_codestring

ISO 3166-1 Alpha 2 Country code where the transaction is being processed

currencystring

ISO 4217 alphabetic currency code of the transaction amount (e.g. MXN, BRL, etc.)

transaction_totalnumber

Total amount of the transaction, including fees and taxes, expressed as a decimal amount in the currency major and minor units

merchant_transaction_referencestring

Merchant supplied unique transaction identifier for correlation

Min length

2

Max length

45

Pattern

^[A-Za-z0-9-_]+

payment_method_codesarray

List of preselected payment methods

Enum values:

["BNKTR"]

BNKTR – Brazil Bank Transfer - PIX

["BNKTR"]

BNKTR – Mexico Bank Transfer – SPEI

["PWC"]

PWC – Mexico Pay with cash – PayCash

Show child attributes

curl --location 'https://merchant-api.paypaga.com/payurl' \
--header 'Authorization: [OAUTH2.0-TOKEN]' \
--data '{
  "merchant_id": "00aa0bb0-0000-0000-00cc-0000dd0eee00",
  "country_code": "MX",
  "currency": "MXN",
  "transaction_total": 10.26,
  "merchant_transaction_reference": "custom-reference-45678",
  "payment_method_codes": [
    "BNKTR"
  ]
}'

(Compatible with Payment Method Preselection via single-item custom list)

This API enables known customer data to be supplied to streamline the customer experience and optimise conversion by minimising manual data entry.

Where all required customer data for a payment method is supplied and validated the customer will automatically receive instructions to complete the payment alleviating the need for any intermediate manual data entry steps.

Title

Description

Title

Countries requiring the parameter	Value	Description
BR	first_name	First name
BR	last_name	Last name
BR	cpf_number	CPF - Cadastro de Pessoas Físicas (11 digits unformatted)

The API numerically validates the CPF before generating the URL. If incorrect, or invalid data is introduced, an error will be returned.

Header Parameters

Authorizationstring

OAuth2.0 Bearer token returned from OAuth2.0 Token Generation API call

Body Parameters

merchant_idstring (uuid)

Merchant identifier provided in the Developer's section of the merchant portal

country_codestring

ISO 3166-1 Alpha 2 Country code where the transaction is being processed

currencystring

ISO 4217 alphabetic currency code of the transaction amount (e.g. MXN, BRL, etc.)

transaction_totalnumber

Total amount of the transaction, including fees and taxes, expressed as a decimal amount in the currency major and minor units

merchant_transaction_referencestring

Merchant supplied unique transaction identifier for correlation

Min length

2

Max length

45

Pattern

^[A-Za-z0-9-_]+

payment_method_codesarray

Sets displayed payment method codes (see PayURL with Custom Payment Method List for more information)

Show child attributes

payment_method_dataarray

Array for pre-selecting and / or fulfilling payment method and customer information.

Show child attributes

Response

200

Object

Response Attributes

transaction_idstring

The transaction Identifier provided by PayPaga.

transaction_datestring

The date the transaction has been generated.

merchant_idstring

The merchant ID that generated this PayURL

payurl_idstring

The unique identifier for this PayURL

messagestring

versionstring

pay_urlstring

The URL to redirect the user to, opening it leads to payment method selection or instructions depending on data provided

400

Object

Response Attributes

transaction_idstring

The transaction Identifier provided by PayPaga

datetimestring

The date the transaction has been generated

error_codenumber

Error code associated with the issue

error_detailsarray

Show child attributes

messagestring

Error message in full

versionstring

curl --location 'https://merchant-api.paypaga.com/payurl' \
--header 'Authorization: [OAUTH2.0-TOKEN]' \
--data '{
  "merchant_id": "00aa0bb0-0000-0000-00cc-0000dd0eee00",
  "country_code": "BR",
  "currency": "BRL",
  "transaction_total": 10.26,
  "merchant_transaction_reference": "custom-reference-45678",
  "payment_method_codes": [
    "BNKTR"
  ],
  "payment_method_data": [
    {
      "payment_method_code": "BNKTR",
      "transaction_fields": [
        {
          "name": "first_name",
          "value": "Test"
        },
        {
          "name": "last_name",
          "value": "Person"
        },
        {
          "name": "cpf_number",
          "value": "12312312312"
        }
      ]
    }
  ]
}'

{
  "transaction_id": "20250220-1532-43a5-a808-b7364a98e016",
  "transaction_date": "2025-02-20",
  "merchant_id": "00aa0bb0-0000-0000-00cc-0000dd0eee00",
  "payurl_id": "729ffd5b-81e4-4808-ab2a-6dcd01c33df9",
  "message": "PayURL Created successfully",
  "version": "0.1",
  "pay_url": "https://payurl.stg.paypaga.com/payment?payurl_id=729ffd5b-81e4-4808-ab2a-6dcd01c33df9"
}

The PayURL could be loaded directly in a new tab or browser window.

In case the PayURL is going to be loaded embedded into the merchant’s website using an <iframe> use the following code:

HTML

<iframe allow="clipboard-write" src="[PASTE-YOUR-pay_url-HERE]"></iframe>

It is important to include the allow="clipboard-write" attribute in the <iframe> to allow the user to use the copy-to-clipboard functionality.

The PayPaga platform provides Transaction Status Notifications that can be sent to a merchant defined API URL and/or to an email address list. Configuration of transaction status notifications is performed via the Developer's section of the Merchant Portal for each environment. The configuration uses a JSON format, the following is an example:

JSON

 {  "notificationActivation": {
    "email": true,
    "api": false
  },
  "apiEndpoint": "https://your-api-endpoint.com/your-webhook",
  "failedWebhookEmailList": [
    "user1@example.com",
    "user2@example.com"
  ],
  "notificationEmailList": [
    "user3@example.com",
    "user4@example.com"
  ]
}

WARNING: The use of a port number in the apiEndpoint value is not allowed.

The payload of the API call and email is as follows:

JSON

 {  "transaction_id": "XXXXX-XXXX-XXXX-XXXXX",
  "status": "Cmpleted",
  "merchant_id": "XXXXX-XXXX-XXXX-XXXXX",
  "transaction_type": "payin or payout",  
  "merchant_transaction_reference": "XXXXXXXX-XXXX-XXX"
}

RESPONSE:

Status code: 200

Body: Empty

Any other status code will be considered failed webhook request.

Request attempts:

Paypaga will attempt the notification request 3 times. If all attempts fail an email will be sent to the configured failedWebhookEmailList email list.

The first retry will occur after 30 seconds with backoff rate multiplier duplicating timeout for every attempt , for example:

First attempt FAILED
30 seconds later second attempt FAILED
60 seconds later third attempt FAILED, send email with Payload to failedWebhookEmailList

In order to retrieve more details about the notified transaction use the applicable ‘Transaction Query’ API relevant to the transaction type.

Body Parameters

transaction_idstring (uuid)

Unique PayPaga assigned transaction identifier

statusstring

New status for the transaction

Enum values:

Approved

Payment provider successfully processed the transaction. Final successful state

Declined

Payment provider declined the transaction during processing. Final failed state.

Error

Unexpected error during processing. Final failed state.

Canceled

Payment provider cancelled the transaction. Final failed sate.

merchant_idstring (uuid)

Merchant identifier provided in the Developer's section of the merchant portal

transaction_typestring

Transaction type

Enum values:

Payin

Pay In transaction

Payout

Pay Out transaction

merchant_transaction_referencestring

Merchant supplied unique transaction identifier for correlation

Max length

45

Pattern

^[A-Za-z0-9-_]+

curl --location 'https://merchant-api.paypaga.com/your-webhook' \
--data '{
  "transaction_id": "XXXXX-XXXX-XXXX-XXXXX",
  "status": "",
  "merchant_id": "XXXXX-XXXX-XXXX-XXXXX",
  "transaction_type": "Payin",
  "merchant_transaction_reference": "XXXXXXXX-XXXX-XXX"
}'

Real-time access to the financial balances of a merchant's account. This can be used for reporting and as a precursor to Pay Out Payment Processing to determine if there is sufficient balance.

Error codes for Query Balance

Error code	Description
107	The merchant balance does not exist
500	Unexpected error

Header Parameters

Authorizationstring Required

OAuth2.0 Bearer token returned from OAuth2.0 Token Generation API call

Query Parameters

country_codestring

ISO 3166-1 Alpha 2 Country code where the transactions were processed. If not provided the balances of all the countries available to the merchant will be returned.

payment_method_codestring

Payment method which processed the transactions. If not provided the balances of all the payment methods available to the merchant will be returned.

Enum values:

BNKTR

Bank Transfer

PWC

PayCash

Path Parameters

merchant_idstring (uuid)Required

Merchant identifier provided in the Developer's section of the merchant portal

Response

200

Object

Success

Response Attributes

country_collectionarray

Container for country balances

Show child attributes

400

Object

Request validation errors

Response Attributes

datetimestring (date-time)

Transaction processing timestamp (UTC timezone)

Pattern

YYYY-MM-DD hh:mm:ss.sss

error_codenumber

Numeric error code. See code catalogue above.

messagestring

Response status description

Max length

200

versionstring

API Version for support purposes

Min length

3

Max length

6

500

Object

Unexpected error

Response Attributes

datetimestring (date-time)

Transaction processing timestamp (UTC timezone)

Pattern

YYYY-MM-DD hh:mm:ss.sss

error_codenumber

Numeric error code. See code catalogue above.

messagestring

Response status description

Max length

200

versionstring

API Version for support purposes

Min length

3

Max length

6

Production:

https://merchant-api.paypaga.com

Sandbox:

https://merchant-api.stg.paypaga.com

1
2

curl --location --globoff 'https://merchant-api.paypaga.com/get_merchant_balance/{merchant_id}?country_code=MX&payment_method_code=BNKTR' \
--header 'Authorization;' \

{
  "country_collection": [
    {
      "country_code": "MX",
      "payment_method_collection": [
        {
          "payment_method_code": "",
          "balance_collection": [
            {
              "transaction_type": "Payin",
              "currency": "MXN",
              "amount": 234461.24
            },
            {
              "transaction_type": "Payout",
              "currency": "MXN",
              "amount": 211015.116
            }
          ]
        },
        {
          "payment_method_code": "BNKTR",
          "balance_collection": [
            {
              "transaction_type": "Payin",
              "currency": "MXN",
              "amount": 167761.96
            },
            {
              "transaction_type": "Payout",
              "currency": "MXN",
              "amount": 150985.764
            }
          ]
        }
      ]
    }
  ]
}

Transaction Status Definitions and Lifecycle

"Initiated": Set when a transaction intent is initiated either when the Payment widget is loaded or the Payin Payment Options API is called..
"Authorizing": Set when a transaction intent is submitted to a Payment Provider for processing when a Payment Processing API endpoint is called. The transaction remains in this state until the Payment Provider responds..
"Pending": Set when a Payment Provider responds to the transaction processing request indicating successful receipt of the transaction.
"Reject" (Final State): Set when a Payment Provider responds to the transaction processing request indicating unsuccessful receipt of the transaction.. Final state indicating a failed transaction.
"Declined" (Final State): Set when a Payment Provider responds to the transaction processing request indicating processing was unsuccessful. Final state indicating a failed transaction.
"Canceled" (Final State): Set when payment processing has been cancelled. Final state indicating a failed transaction.
"Refund" (Not yet implemented): This status is reserved for future use for where a transaction is reversed.
"Approved" (Final State): Set when a Payment Provider confirms the successful completion of the payment lifecycle. Final state indicating a successful transaction.
"Error" (Final State): Set when an unexpected errors occurs during processing. Final state indicating a failed transaction.
"Expired" (Final State): Set when a Pending transaction reach the time limit to be completed when an end user interaction is required. Final State indicating an incomplete transaction.

Sections

Introduction

Authorization

Standard Codes and Values

Standards that define the possible values for common data types used in all APIs. Country

Currency

What made this section unhelpful for you?

Pay In - Direct API Integration

Pay Out - Direct API Integration

Pay In - PayURL Integration

What made this section unhelpful for you?

PayURL Service

Header Parameters

Body Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

PayURL with Custom Payment Method List

Header Parameters

Body ParametersExpand all

What made this section unhelpful for you?

What made this section unhelpful for you?

PayURL with Customer Data in Request

Header Parameters

Body ParametersExpand all

ResponseExpand all

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Redirect the user to the generated PayURL

What made this section unhelpful for you?

Transactions Status Notification

Body Parameters

What made this section unhelpful for you?

What made this section unhelpful for you?

Query Balance

Header Parameters

Query Parameters

Path Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

Response

What made this section unhelpful for you?

Appendix

Transaction Status Definitions and Lifecycle

What made this section unhelpful for you?

Standards that define the possible values for common data types used in all APIs.
Country

Response

Body Parameters

Body Parameters

Response

Response