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 the merchant should create a fresh new attempt, where initiating a fresh new attempt at a later time may potentially result in a successful outcome. PPRO will populate this flag when we recognize that a payment received a hard decline.
Note: Similarly, this is dependent on the information provided by our acquirers & may not be provide for all failures.

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

7. Create Recurring Card Payments with a Payment Agreement

Payment Agreements are the recommended path to run recurring payments in a standard way across payment methods. A Payment Agreement binds a Payment Instrument to a context and groups subsequent charges under one lineage.

Why use Payment Agreements for Card Payments?
You can reuse a stored instrumentId for subsequent card charges without an agreement (see section 6) but Payment Agreements are still a better approach to manage recurring billing consumer contracts.

A Payment Agreement captures the consumer’s consent to be charged later, links that consent to a stored payment instrument, and groups all related charges under one lineage. That gives you a single, payment-method-agnostic model for recurring payments across cards and local payment methods. With Payment Agreements you get:

A consistent integration as you add more payment methods

Subscription lineage across the full charge history, making it easy to fetch all payment charges within that agreement

Simpler subsequent charges: charge by agreementId, without managing scheme authorization references (NTI) or the network transaction link references (TLID) yourself.

Explicit lifecycle and revocation (including who revoked the agreement).

Access to future recurring capabilities built on agreements (scheduling, smart retries, automated agreement management)

Learn more about Payment Agreements and recurring payments.

The card recurring flow with agreements is:

Create a Payment Agreement with card details and an initialPaymentCharge.
Confirm the agreement is ACTIVE (and the initial charge outcome, if relevant).
Create subsequent recurring charges against the agreement.

Card validation for agreements

When setting up a card agreement, the best way to validate the card is with a zero-amount authorization via initialPaymentCharge not with the instrument-level validate object.

Approach	Use for card agreements?
`initialPaymentCharge.amount.value = 0`	Yes — recommended. Runs a zero-amount authorization as part of agreement setup.
`instrument.validate` (native instrument validation)	No. Do not use this for card instrument types when creating agreements.

Use:

Zero-amount initialPaymentCharge when the consumer is saving a card / establishing a mandate without paying yet (validation-only setup i.e. Link Only).
Non-zero initialPaymentCharge when the consumer pays on signup (i.e. Link & Pay).

Important
For CARD instruments, prefer validating through initialPaymentCharge with amount.value: 0. Do not rely on instrument.validate for this flow.

scheduleType under an agreement
When charging against an agreement:

If the agreement has a frequency, charges default to scheduleType: SCHEDULED

If no frequency is set, charges default to scheduleType: UNSCHEDULED

For dunning retries of a failed scheduled charge, use scheduleType: SCHEDULED_RETRY with initiator: MERCHANT
See Recurring payments.

7.1 Create a Payment Agreement and validate the card (zero-amount initial charge).

Create the agreement with RAW_CARD details and an initialPaymentCharge of 0.

Request

POST /v1/payment-agreements

{
  "paymentMethod": "CARD",
  "merchantPaymentAgreementReference": "YOUR_PAYMENT_AGREEMENT_REFERENCE",
  "description": "Monthly Subscription",
  "startDate": "2025-07-22T00:00:00.000Z",
  "frequency": {
    "type": "MONTHLY",
    "interval": 1
  },
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "amountType": "EXACT",
  "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"
  },
  "initialPaymentCharge": {
    "merchantPaymentChargeReference": "YOUR_INITIAL_VALIDATION_REFERENCE",
    "paymentDescriptor": "CARD VALIDATION",
    "initiator": "CONSUMER",
    "scheduleType": "SCHEDULED",
    "autoCapture": false,
    "amount": {
      "value": 0,
      "currency": "BRL"
    }
  },
  "webhooksUrl": "https://notification.service.com/"
}

Response

{
  "id": "agr_VgEBeWxNu2Vyyo6FyWkSP",
  "status": "ACTIVE",
  "description": "Monthly Subscription",
  "paymentMethod": "CARD",
  "merchantPaymentAgreementReference": "YOUR_PAYMENT_AGREEMENT_REFERENCE",
  "frequency": {
    "type": "MONTHLY",
    "interval": 1
  },
  "startDate": "2025-07-22T00:00:00.000Z",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "amountType": "EXACT",
  "instrumentId": "instr_cFBjegcOCDZRZmW8hGNaM",
  "consumer": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+5511223344",
    "country": "BR",
    "locale": "pt-BR",
    "taxIdentification": "12345678909"
  },
  "initialPaymentChargeId": "charge_g8SsPBfIJcsXckohcFccB",
  "history": [
    {
      "id": "ahist_A3FIK08zwCA5DWgI71rqi",
      "status": "ACTIVE",
      "createdAt": "2025-07-22T14:29:28.201Z"
    }
  ],
  "createdAt": "2025-07-22T14:29:28.201Z",
  "updatedAt": "2025-07-22T14:29:28.201Z"
}

Store:

id — the Payment Agreement ID used for subsequent charges
instrumentId — the vaulted card instrument
initialPaymentChargeId — the zero-amount validation charge

Handling the zero-amount charge
Retrieve the initial Payment Charge (GET /v1/payment-charges/{initialPaymentChargeId}) or rely on webhooks to confirm authorization succeeded before treating the card as validated for billing.
Do not ship goods or start paid service until a successful non-zero payment charge (when applicable). A successful zero-amount validation only confirms the card can be authorized.

Optional: include authenticationSettings with EXTERNAL_3DS on the agreement / initial charge when you already have 3DS results from your MPI. See 3D Secure.

7.2 Create a Payment Agreement with a first paid charge (link and pay)

If the consumer pays at signup, use the same agreement creation call with a non-zero initialPaymentCharge.

Request

POST /v1/payment-agreements

{
  "paymentMethod": "CARD",
  "merchantPaymentAgreementReference": "YOUR_PAYMENT_AGREEMENT_REFERENCE",
  "description": "Monthly Subscription",
  "startDate": "2025-07-22T00:00:00.000Z",
  "frequency": {
    "type": "MONTHLY",
    "interval": 1
  },
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "amountType": "EXACT",
  "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"
  },
  "initialPaymentCharge": {
    "merchantPaymentChargeReference": "YOUR_FIRST_PAYMENT_REFERENCE",
    "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
    "initiator": "CONSUMER",
    "scheduleType": "SCHEDULED",
    "autoCapture": true,
    "amount": {
      "value": 10000,
      "currency": "BRL"
    }
  },
  "webhooksUrl": "https://notification.service.com/"
}

Failed initial charge vs active agreement
In some flows the agreement can become ACTIVE even if the initial Payment Charge fails. In that case you can retry against the agreement. Only fulfill after a successful payment charge notification. See Payment agreement.

7.3 Create a subsequent recurring payment against the agreement

Once the agreement is ACTIVE, create merchant-initiated recurring charges (MITs) with:

POST /v1/payment-agreements/{agreementId}/payment-charges

You do not need to resend card details or instrumentId as the agreement already references the stored instrument.

Request

{
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "initiator": "MERCHANT",
  "merchantPaymentChargeReference": "YOUR_RECURRING_PAYMENT_REFERENCE",
  "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
  "autoCapture": true
}

Response

{
  "id": "charge_S5MjG1BsPftrmvmwvPzBo",
  "paymentMethod": "CARD",
  "paymentMedium": "ECOMMERCE",
  "initiator": "MERCHANT",
  "scheduleType": "SCHEDULED",
  "instrumentId": "instr_cFBjegcOCDZRZmW8hGNaM",
  "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_RECURRING_PAYMENT_REFERENCE",
      "createdAt": "2025-08-22T14:42:37.987Z",
      "updatedAt": "2025-08-22T14:42:37.987Z"
    }
  ],
  "captures": [
    {
      "id": "capture_R8dbctfLOdp7dqCHJE3xL",
      "amount": 10000,
      "status": "CAPTURED",
      "merchantCaptureReference": "YOUR_RECURRING_PAYMENT_REFERENCE",
      "createdAt": "2025-08-22T14:42:37.987Z",
      "updatedAt": "2025-08-22T14:42:37.987Z"
    }
  ],
  "refunds": [],
  "voids": [],
  "createdAt": "2025-08-22T14:42:37.014Z",
  "updatedAt": "2025-08-22T14:42:37.987Z"
}

Recommended pattern summary

Sr	Step	Endpoint	What to send
1a	Setup + validate card	`POST /v1/payment-agreements`	`RAW_CARD` + `initialPaymentCharge.amount.value = 0`
1b	Setup + first payment	`POST /v1/payment-agreements`	`RAW_CARD` + non-zero `initialPaymentCharge`
2	Confirm outcome	Listen to Webhooks (or) `GET` charge & agreement	Agreement `ACTIVE`; charge authorized/captured as expected
3	Recurring Merchant Initiated Transaction (MIT)	`POST /v1/payment-agreements/{agreementId}/payment-charges`	Amount (+ optional capture/descriptor/reference)
4	Cancel mandate	`POST /v1/payment-agreements/{agreementId}/revocations`	Revoke when billing should stop

Quickstart: Cards

1. Create a Payment Charge

Request

Response

2. Handle the payment result

Handling failures

3. Capture a payment

Request

Response

5. Refund a payment

Request

Response

6. Create a Payment Charge with an existing Payment Instrument

Payment Agreements

Merchant Initiated Transactions using Stored Payment Instrument Id

Response

Consumer Initiated Transactions using Stored Payment Instrument Id

Respons

Request using CARD_PPRO_VAULTED Instrument

Response

7. Create Recurring Card Payments with a Payment Agreement

Why use Payment Agreements for Card Payments?

Card validation for agreements

Important

`scheduleType` under an agreement

7.1 Create a Payment Agreement and validate the card (zero-amount initial charge).

Request

Response

Handling the zero-amount charge

7.2 Create a Payment Agreement with a first paid charge (link and pay)

Request

Failed initial charge vs active agreement

7.3 Create a subsequent recurring payment against the agreement

Request

Response

Recommended pattern summary

1. Create a Payment Charge

Request

Response

2. Handle the payment result

Handling failures

3. Capture a payment

Request

Response

5. Refund a payment

Request

Response

6. Create a Payment Charge with an existing Payment Instrument

Payment Agreements

Merchant Initiated Transactions using Stored Payment Instrument Id

Response

Consumer Initiated Transactions using Stored Payment Instrument Id

Respons

Request using CARD_PPRO_VAULTED Instrument

Response

7. Create Recurring Card Payments with a Payment Agreement

Why use Payment Agreements for Card Payments?

Card validation for agreements

Important

scheduleType under an agreement

7.1 Create a Payment Agreement and validate the card (zero-amount initial charge).

Request

Response

Handling the zero-amount charge

7.2 Create a Payment Agreement with a first paid charge (link and pay)

Request

Failed initial charge vs active agreement

7.3 Create a subsequent recurring payment against the agreement

Request

Response

Recommended pattern summary

`scheduleType` under an agreement