💡
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:

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 shipping details and basket contents.
3D Secure authentication (optional): Provide 3D Secure authentication values obtained through a third party 3DS MPI (merchant plug-in) prior to creating the payment charge. 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": {
    "billingAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+5511223344",
      "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
      "postalCode": "01452-002",
      "city": "São Paulo – SP",
      "country": "BR"
    },
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+5511223344",
    "country": "BR",
    "locale": "pt-BR",
    "taxIdentification": "12345678909"
  },
  "order": {
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+5511223344",
      "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
      "postalCode": "01452-002",
      "city": "São Paulo – SP",
      "country": "BR"
    },
    "orderItems": [
      {
        "name": "White T-Shirt",
        "quantity": 1,
        "amount": 10000
      }
    ],
    "orderReferenceNumber": "YOUR_ORDER_REFERENCE_NUMBER",
    "totalTaxAmount": 1670
  },
  "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

TBD

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.

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_w60qDSiYVgzrjdhOsZRLG",
  "amount": 10000,
  "status": "CAPTURED",
  "merchantCaptureReference": "YOUR_CAPTURE_REFERENCE",
  "createdAt": "2025-04-23T18:58:08.100Z",
  "updatedAt": "2025-04-23T18:58:08.100Z",
  "_links": {
    "payment_charge": {
      "href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d"
    }
  }
}

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_iKCiv8S92fgDjFpDiV5R6",
  "amount": 600,
  "status": "REFUNDED",
  "merchantRefundReference": "YOUR_REFUND_REFERENCE",
  "createdAt": "2025-04-30T08:42:53.849Z",
  "updatedAt": "2025-04-30T08:42:53.849Z",
  "_links": {
    "payment_charge": {
      "href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d"
    }
  }
}