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": {
    "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

{
    "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",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+5511223344",
            "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
            "postalCode": "01452-002",
            "city": "São Paulo – SP",
            "country": "BR"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "White T-Shirt",
                "quantity": 1,
                "amount": 10000
            }
        ],
        "shippingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+5511223344",
            "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
            "postalCode": "01452-002",
            "city": "São Paulo – SP",
            "country": "BR"
        },
        "industryData": [],
        "orderReferenceNumber": "YOUR_ORDER_REFERENCE_NUMBER",
        "totalTaxAmount": 1670
    },
    "authorizations": [
        {
            "id": "authz_AXeVBPRKZrWtZBFncGHKr",
            "amount": 10000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "internalData": {
                "processorAuthorizationContext": {
                    "descriptor": "Cielo descriptor"
                }
            },
            "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",
    "internalData": {
        "processorAuthorizationContext": {
            "descriptor": "Cielo descriptor"
        },
        "merchantId": "26819159-3774-4ad7-bf5f-854dee69895e",
        "autoCapture": false
    },
    "_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.

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"
        }
    },
    "internalData": {}
}

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": {
    "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
  },
  "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",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+5511223344",
            "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
            "postalCode": "01452-002",
            "city": "São Paulo – SP",
            "country": "BR"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "White T-Shirt",
                "quantity": 1,
                "amount": 10000
            }
        ],
        "shippingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+5511223344",
            "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
            "postalCode": "01452-002",
            "city": "São Paulo – SP",
            "country": "BR"
        },
        "industryData": [],
        "orderReferenceNumber": "YOUR_ORDER_REFERENCE_NUMBER",
        "totalTaxAmount": 1670
    },
    "authorizations": [
        {
            "id": "authz_VyZzOsjHGzFXkpqe0CODf",
            "amount": 10000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "internalData": {
                "processorAuthorizationContext": {
                    "descriptor": "Cielo descriptor"
                }
            },
            "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",
    "internalData": {
        "processorAuthorizationContext": {
            "descriptor": "Cielo descriptor"
        },
        "merchantId": "26819159-3774-4ad7-bf5f-854dee69895e",
        "autoCapture": true
    },
    "_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": {
        "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
    },
    "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",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+5511223344",
            "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
            "postalCode": "01452-002",
            "city": "São Paulo – SP",
            "country": "BR"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "White T-Shirt",
                "quantity": 1,
                "amount": 10000
            }
        ],
        "shippingAddress": {
            "firstName": "John",
            "lastName": "Smith",
            "phoneNumber": "+5511223344",
            "street": "Av. Brig. Faria Lima, 1309 – Pinheiros",
            "postalCode": "01452-002",
            "city": "São Paulo – SP",
            "country": "BR"
        },
        "industryData": [],
        "orderReferenceNumber": "YOUR_ORDER_REFERENCE_NUMBER",
        "totalTaxAmount": 1670
    },
    "authorizations": [
        {
            "id": "authz_rUUWH5PQqxzQ92tUjyMqi",
            "amount": 10000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
            "internalData": {
                "processorAuthorizationContext": {
                    "descriptor": "Cielo descriptor"
                }
            },
            "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",
    "internalData": {
        "processorAuthorizationContext": {
            "descriptor": "Cielo descriptor"
        },
        "merchantId": "26819159-3774-4ad7-bf5f-854dee69895e",
        "autoCapture": true
    },
    "_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 11 days ago