Documentation

Quickstart: Cards

💡

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 designed with a rich data model that enables a single integration and reuse of data points across many payment methods. To minimize the upfront effort, many fields are optional by default (unless the specified payment method requires the data). This approach enables you to build the expected payload incrementally.

The Payment Charge expects data points around:

  1. Basic details: Provide the amount, currency, payment descriptor, merchant references.
  2. 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.
  3. Consumer details (optional): Include the consumer's name and billing address details.
  4. Order details (optional): Include shipping details and basket contents.
  5. 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.

Captures 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- and merchant-initiated payments.

📘

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.

Request using Payment Instrument ID

You can use the Payment Instrument ID that is returned in the response during Payment Charge creation for a RAW_CARD instrument type to make subsequent payments using the same Payment Instrument.

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"
  },
  "instrumentId": "instr_eUb7ujxCLHWN7YOHnLaLf",
  "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"
        }
    }
}

Request using CARD_PPRO_VAULTED Instrument

Any RAW_CARD data provided will be converted to the instrument type CARD_PPRO_VAULTED which has the PAN replaced with an alias. It is possible to get the full instrument details via API by using the Retrieve Instrument call and these can also be referenced in the Payment Charge request.

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"
        }
    }
}

Updated 1 day ago