📘
This guide assumes a basic understanding of PPRO's core API objects and common API functionality.

PPRO provides access to payment products across the globe, covering both local payment methods and cards. This guide focuses on the technical integration for accepting card payments.

1. Create a Payment Charge

Create a Payment Charge by submitting a POST request to /v1/payment-charges.

The Payment Charge is built on a rich, extensible data model that supports a single integration and reuse of common data points across multiple payment methods. To reduce upfront integration effort, most fields are optional by default, unless explicitly required by a given payment method. This allows the payload to be constructed incrementally as additional data becomes available or is needed.

The Payment Charge expects data points around:

Basic details: Provide the amount, currency, payment descriptor, merchant references.
Card details: Provide the card details. Do not store, transmit, or process raw card data (e.g., full card numbers, CVV) unless compliant with PCI DSS standards. Improper handling can lead to security vulnerabilities, legal consequences, and compliance violations.
Consumer details (optional): Include the consumer's name and billing address details.
Order details (optional): Include order item details and shipping details.
3D Secure authentication (optional): Provide 3D Secure authentication values obtained through a third party 3DS MPI (merchant plug-in) prior to creating the Payment harge. Learn more about 3D Secure.

Request

POST /v1/payment-charges

{
  "paymentMethod": "CARD",
  "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
  "initiator": "CONSUMER",
  "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
  "paymentMedium": "ECOMMERCE",
  "scheduleType": "UNSCHEDULED",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "instrument": {
    "type": "RAW_CARD",
    "details": {
      "brand": "VISA",
      "number": "4111111111111111",
      "cvv": "123",
      "holderName": "John Smith",
      "expiryMonth": 1,
      "expiryYear": 2030
    }
  },
  "consumer": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+5511223344",
    "country": "BR",
    "locale": "pt-BR",
    "taxIdentification": "12345678909"
  },
  "authenticationSettings": [
    {
      "type": "EXTERNAL_3DS",
      "settings": {
        "authenticationStatus": "SUCCESS",
        "authenticationValue": "e3f7a0c2-fff8-4fb8-afab-dbae6e17c9cc",
        "eci": "01",
        "version": "2.0.0",
        "externalId": "a7fe5eae-d5bb-4f57-a946-2125c3c32801",
        "challenge": {
          "preference": "NO_CHALLENGE_REQUESTED",
          "outcome": "FRICTIONLESS",
          "exemptionReason": "LOW_VALUE"
        }
      }
    }
  ],
  "autoCapture": false,
  "webhooksUrl": "https://notification.service.com/"
}

Response

{
    "id": "charge_g8SsPBfIJcsXckohcFccB",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "CONSUMER",
    "scheduleType": "UNSCHEDULED",
    "instrumentId": "instr_eUb7ujxCLHWN7YOHnLaLf",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "BR",
    "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
    "status": "CAPTURE_PENDING",
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+5511223344",
        "country": "BR",
        "locale": "pt-BR",
        "taxIdentification": "12345678909"
    },
    "authorizations": [
        {
            "id": "authz_AXeVBPRKZrWtZBFncGHKr",
            "amount": 10000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "createdAt": "2025-07-22T14:29:28.201Z",
            "updatedAt": "2025-07-22T14:29:28.201Z"
        }
    ],
    "captures": [],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-07-22T14:29:23.379Z",
    "updatedAt": "2025-07-22T14:29:28.201Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_g8SsPBfIJcsXckohcFccB/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_g8SsPBfIJcsXckohcFccB/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_g8SsPBfIJcsXckohcFccB/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_g8SsPBfIJcsXckohcFccB/voids"
        }
    }
}

2. Handle the payment result

The authorization outcome is included in the response to the Payment Charge creation request and can be used to display the result to the consumer.

📘
Handling failures
In the case of a failure, PPRO will pass issuer/acquirer and card scheme details, where possible. This allows you to optimise your retrial logic to avoid making excessive attempts and incurring scheme fines.
In the example below, we can see:

failure.providerFailureCode:51 - ISO-format issuer/acquirer decline code 51, indicating the customer does not have enough funds in their account.
Note: Not all acquirers return ISO-format decline codes, but we will always pass them when available.

failure.isRetryable:true - This is an optional flag that indicates whether a a payment can be retried or not. PPRO will populate this flag when we recognise that a payment received a hard decline.
Note: Similarly, this is dependent on the information provided by our acquirers.

failure.additionalData.merchantAdviceCode - The Merchant Advice Code (MAC) which accompanies some decline codes from Mastercard. In this case, 25 indicates the authorization should be retried after 24 hours.
{
  "id": "charge_g8SsPBfIJcsXckohcFccB",
  "status": "FAILED",
  "failure": {
    "failureType": "PROVIDER_DECLINE",
    "failureCode": "INSUFFICIENT_FUNDS",
    "providerFailureCode": "51",
    "failureMessage": "Insufficient funds",
    "isRetryable": true,
    "additionalData": {
      "merchantAdviceCode": "25"
		}
  },
  ... // other fields
}
See more details on Error Represenation via PPRO.

3. Capture a payment

While an authorization is merely a hold on the amount specified, a capture initiates the movement of funds. Captures can be submitted through the API using the Create capture call.

PPRO supports multiple partial captures up to the authorized amount. Learn more about captures.

Sending autoCapture: trueduring the Payment Charge creation will automatically capture the full amount upon successful authorization, resulting in the Payment Charge ending with a CAPTURED status.

Request

POST /v1/payment-charges/{paymentChargeId}/captures

{
  "amount": 10000,
  "merchantCaptureReference": "YOUR_CAPTURE_REFERENCE"
}

Response

{
    "id": "capture_0xVTsSYTb2fabNB5qFDnH",
    "amount": 10000,
    "status": "CAPTURED",
    "merchantCaptureReference": "YOUR_CAPTURE_REFERENCE",
    "createdAt": "2025-07-22T14:32:02.811Z",
    "updatedAt": "2025-07-22T14:32:02.811Z",
    "_links": {
        "payment_charge": {
            "href": "/v1/payment-charges/charge_g8SsPBfIJcsXckohcFccB"
        }
    }
}

5. Refund a payment

PPRO supports full and partial refunds up to the captured amount. Learn more about refunds.

Refunds can be submitted through the API using the Create refund call.

Request

POST /v1/payment-charges/{paymentChargeId}/refunds

{
  "amount": 600,
  "merchantRefundReference": "YOUR_REFUND_REFERENCE"
}

Response

{
    "id": "refund_EVAUusIVxomSB7wYJTpih",
    "amount": 6000,
    "status": "REFUNDED",
    "merchantRefundReference": "YOUR_REFUND_REFERENCE",
    "createdAt": "2025-07-22T14:32:59.612Z",
    "updatedAt": "2025-07-22T14:32:59.612Z",
    "_links": {
        "payment_charge": {
            "href": "/v1/payment-charges/charge_g8SsPBfIJcsXckohcFccB"
        }
    }
}

6. Create a Payment Charge with an existing Payment Instrument

All card payments processed through PPRO will have PAN information tokenized and securely stored in the PPRO Vault. This tokenized card information can be reused for future consumer initiated transactions (CIT) and merchant initiated transactions (MIT).

📘
Payment Agreements
Payment Instruments can also be reused implicitly via Payment Agreements.
A Payment Agreement serves as a container object that groups and manages multiple payment charges. It is specifically designed to support recurring payments. Learn more about recurring payments.

Merchant Initiated Transactions using Stored Payment Instrument Id

The Stored Payment Instrument ID returned in the Payment Charge response for a RAW_CARD instrument type can be reused for subsequent payments with the same payment instrument, removing the need for you to store raw card PANs on your side. For MIT's you can just simply provide the instrumentId

POST /v1/payment-charges

{
  "paymentMethod": "CARD",
  "initiator": "MERCHANT",
  "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
  "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
  "paymentMedium": "ECOMMERCE",
  "scheduleType": "RECURRING",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "instrumentId": "instr_eUb7ujxCLHWN7YOHnLaLf",      //Instrument Id from the earlier payment charge
  "consumer": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+5511223344",
    "country": "BR",
    "locale": "pt-BR",
    "taxIdentification": "12345678909"
  },
  "autoCapture": true,
  "webhooksUrl": "https://notification.service.com/"
}

Response

{
    "id": "charge_S5MjG1BsPftrmvmwvPzBo",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "MERCHANT",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_eUb7ujxCLHWN7YOHnLaLf",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "BR",
    "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
    "status": "CAPTURED",
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+5511223344",
        "country": "BR",
        "locale": "pt-BR",
        "taxIdentification": "12345678909"
    },
    "authorizations": [
        {
            "id": "authz_VyZzOsjHGzFXkpqe0CODf",
            "amount": 10000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "createdAt": "2025-07-22T14:42:37.987Z",
            "updatedAt": "2025-07-22T14:42:37.987Z"
        }
    ],
    "captures": [
        {
            "id": "capture_R8dbctfLOdp7dqCHJE3xL",
            "amount": 10000,
            "status": "CAPTURED",
            "merchantCaptureReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "createdAt": "2025-07-22T14:42:37.987Z",
            "updatedAt": "2025-07-22T14:42:37.987Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-07-22T14:42:37.014Z",
    "updatedAt": "2025-07-22T14:42:37.987Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/voids"
        }
    }
}

Consumer Initiated Transactions using Stored Payment Instrument Id

Similar to the above use case, the Stored Payment Instrument ID returned in the Payment Charge response for a RAW_CARD instrument type can also be used to process subsequent consumer-initiated payments, with the CVV provided as the trust signal. This removes the need for the consumer to re-enter their PAN and avoids the merchant storing raw card details. As part of the checkout flow, the consumer is prompted only for the CVV, which is passed to PPRO as part of the Payment Charge creation request itself.

POST /v1/payment-charges

{
  "paymentMethod": "CARD",
  "initiator": "CONSUMER",
  "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
  "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
  "paymentMedium": "ECOMMERCE",
  "scheduleType": "RECURRING",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "instrumentId": "instr_eUb7ujxCLHWN7YOHnLaLf",      //Instrument Id from the earlier payment charge
  "instrumentUpdateDetails": {
      "type": "RAW_CARD",
      "details": {
          "cvv": "123"				                        //For CITs provide the CVV here
        }
   },
  "consumer": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+5511223344",
    "country": "BR",
    "locale": "pt-BR",
    "taxIdentification": "12345678909"
  },
  "autoCapture": true,
  "webhooksUrl": "https://notification.service.com/"
}

Respons

{
    "id": "charge_S5MjG1BsPftrmvmwvPzBo",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "CONSUMER",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_eUb7ujxCLHWN7YOHnLaLf",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "BR",
    "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
    "status": "CAPTURED",
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+5511223344",
        "country": "BR",
        "locale": "pt-BR",
        "taxIdentification": "12345678909"
    },
    "authorizations": [
        {
            "id": "authz_VyZzOsjHGzFXkpqe0CODf",
            "amount": 10000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "createdAt": "2025-07-22T14:42:37.987Z",
            "updatedAt": "2025-07-22T14:42:37.987Z"
        }
    ],
    "captures": [
        {
            "id": "capture_R8dbctfLOdp7dqCHJE3xL",
            "amount": 10000,
            "status": "CAPTURED",
            "merchantCaptureReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "createdAt": "2025-07-22T14:42:37.987Z",
            "updatedAt": "2025-07-22T14:42:37.987Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-07-22T14:42:37.014Z",
    "updatedAt": "2025-07-22T14:42:37.987Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_S5MjG1BsPftrmvmwvPzBo/voids"
        }
    }
}

Request using CARD_PPRO_VAULTED Instrument

Any RAW_CARD data provided is converted into a CARD_PPRO_VAULTED instrument, where the PAN is replaced with an alias. The full instrument details can be retrieved via the Retrieve Instrument API and referenced in subsequent Payment Charge requests.

POST /v1/payment-charges

{
    "paymentMethod": "CARD",
    "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
    "initiator": "MERCHANT",
    "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
    "paymentMedium": "ECOMMERCE",
    "scheduleType": "RECURRING",
    "amount": {
        "value": 10000,
        "currency": "BRL"
    },
    "instrument": {
        "type": "CARD_PPRO_VAULTED",
        "details": {
            "brand": "VISA",
            "bin": "411111",
            "last4Digits": "1111",
            "expiryMonth": 1,
            "expiryYear": 2030,
            "holderName": "John Smith",
            "panAlias": "alias_TARyEdlDnWu3EFUh6HFWR",
            "isCvvPresent": false
        }
    },
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+5511223344",
        "country": "BR",
        "locale": "pt-BR",
        "taxIdentification": "12345678909"
    },
    "autoCapture": true,
    "webhooksUrl": "https://notification.service.com/"
}

Response

{
    "id": "charge_W6nT0d3lAHJgc74aPC1y2",
    "paymentMethod": "CARD",
    "paymentMedium": "ECOMMERCE",
    "initiator": "MERCHANT",
    "scheduleType": "RECURRING",
    "instrumentId": "instr_aenjo7uJ8N1U1yPHNyi1I",
    "instrumentUpdated": false,
    "currency": "BRL",
    "country": "BR",
    "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
    "status": "CAPTURED",
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+5511223344",
        "country": "BR",
        "locale": "pt-BR",
        "taxIdentification": "12345678909"
    },
    "authorizations": [
        {
            "id": "authz_rUUWH5PQqxzQ92tUjyMqi",
            "amount": 10000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "createdAt": "2025-07-22T14:54:51.446Z",
            "updatedAt": "2025-07-22T14:54:51.446Z"
        }
    ],
    "captures": [
        {
            "id": "capture_qfF0MErPKZB0eah5TkXv9",
            "amount": 10000,
            "status": "CAPTURED",
            "merchantCaptureReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "createdAt": "2025-07-22T14:54:51.446Z",
            "updatedAt": "2025-07-22T14:54:51.446Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-07-22T14:54:50.485Z",
    "updatedAt": "2025-07-22T14:54:51.446Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_W6nT0d3lAHJgc74aPC1y2/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_W6nT0d3lAHJgc74aPC1y2/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_W6nT0d3lAHJgc74aPC1y2/refunds"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_W6nT0d3lAHJgc74aPC1y2/voids"
        }
    }
}