Overview
Orkestra supports processing credit and debit card payments, allowing merchants to offer card transactions with full control over authorization, capture, and installments.
In Brazil, merchants must explicitly ask the customer whether they are using a Credit Card (CREDIT_CARD) or Debit Card (DEBIT_CARD) since the identification via PAN is not automatically possible.
To create a card payment, set the paymentMethod to either CREDIT_CARD or DEBIT_CARD in the order transaction and provide the necessary card details.
📝 Minimum Required Fields for Card Payment
When creating an Order for a card payment, the following fields are mandatory:
| Field | Type | Description |
|---|---|---|
charges[].customer.firstName | String | Customer’s first name. |
charges[].customer.lastName | String | Customer’s last name. |
charges[].customer.document | String | Customer’s document number. |
charges[].customer.documentType | Enum | Document type — see supported types below. |
charges[].transactions[].paymentMethod | Enum | Must be set to CREDIT_CARD or DEBIT_CARD. |
charges[].transactions[].creditCard.card.number | String | Card number (PAN). |
charges[].transactions[].creditCard.card.expiresAt | String | Expiry date in MM/YYYY format. |
charges[].transactions[].creditCard.card.securityCode | String | Card Verification Value (CVV / CVC). |
⚙️ Optional Card Fields
| Field | Type | Description |
|---|---|---|
charges[].transactions[].creditCard.card.holder.firstName | String | Cardholder’s first name (if different from customer). |
charges[].transactions[].creditCard.card.holder.lastName | String | Cardholder’s last name. |
charges[].transactions[].creditCard.card.holder.documentType | Enum | Cardholder’s document type. |
charges[].transactions[].creditCard.card.holder.document | String | Cardholder’s document number. |
charges[].transactions[].creditCard.card.billingAddress | Object | Billing address (same structure as livingAddress). |
charges[].transactions[].creditCard.card.issuingCountry | Enum (ISO Alpha-3) | Country code of card issuing country (e.g., BRA, USA, ARG). |
📦 options Object
You can control the behavior of the card processing via the options object:
| Field | Type | Default | Description |
|---|---|---|---|
installments | Integer | 1 | Number of installments for the payment. |
autoCapture | Boolean | true | Whether to capture automatically after authorization. |
anticipate | Integer | null | Days to anticipate the receivables. |
threeDSecure | Boolean | true | Whether to enforce 3D Secure authentication. |
retryOnFailure | Boolean | false | Whether to automatically retry failed transactions on retryable decline reasons. |
captureDelay | Integer | 0 | Delay in minutes before capture happens after authorization. |
noCaptureBehavior | Enum | VOID | What to do if a capture is not performed: VOID or CAPTURE. |
🆔 DocumentTypeEnum
The following document types are supported depending on the country:
| Enum | Country |
|---|---|
CPF | Brazil |
CNPJ | Brazil |
CUIT | Argentina |
RFC | Mexico |
CURP | Mexico |
CC | Colombia |
NIT | Colombia |
TI | Colombia |
RUT | Chile |
DNI | Peru |
CI | Ecuador |
CE | Colombia, Peru |
RUC | Ecuador, Peru |
PASSPORT | All countries |
📦 Example: Card Payment Request
{
"merchantOrderId": "order-12345",
"softDescriptor": "Orkestra Store",
"amount": 5000,
"currency": "BRL",
"allowsThirdPartyPayments": false,
"charges": [
{
"customer": {
"firstName": "Camila",
"lastName": "Silva",
"document": "12345678900",
"documentType": "CPF"
},
"transactions": [
{
"paymentMethod": "CREDIT_CARD",
"creditCard": {
"card": {
"number": "4111111111111111",
"expiresAt": "12/2026",
"securityCode": "123",
"holder": {
"firstName": "Camila",
"lastName": "Silva",
"document": "12345678900",
"documentType": "CPF"
},
"billingAddress": {
"street": "Av. Paulista",
"number": "1000",
"complement": "Ap 12",
"neighborhood": "Bela Vista",
"zipCode": "01310000",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"mainInformation": "Av. Paulista, 1000",
"secondaryInformation": "Ap 12",
"latitude": -23.561684,
"longitude": -46.656139
},
"issuingCountry": "BRA"
},
"options": {
"installments": 3,
"autoCapture": true,
"anticipate": 30,
"threeDSecure": true,
"retryOnFailure": true,
"captureDelay": 5,
"noCaptureBehavior": "VOID",
"antifraud": {
"provider": "ClearSale",
"scoreThreshold": 70,
"metadata": {
"ipAddress": "1.2.3.4",
"deviceFingerprint": "abc123xyz",
"customerSince": "2020-01-01",
"previousOrders": 2
}
}
}
}
}
]
}
]
}
🔁 Payment Flow Overview
- You create an order with
paymentMethodset toCREDIT_CARDorDEBIT_CARD. - Orkestra processes the card authorization.
- If autoCapture is enabled, the transaction will be captured immediately.
- If 3DS is enabled, authentication will be performed automatically.
- Payment confirmation is sent via webhook.
📦 Example: Card Payment Response
{
"id": 987654,
"merchantOrderId": "order-12345",
"softDescriptor": "Orkestra Store",
"amount": 5000,
"currency": "BRL",
"status": "PAID",
"allowsThirdPartyPayments": false,
"charges": [
{
"id": 123456,
"amount": 5000,
"status": "PAID",
"customer": {
"firstName": "Camila",
"lastName": "Silva",
"document": "12345678900",
"documentType": "CPF"
},
"transactions": [
{
"id": 789123,
"amount": 5000,
"paymentMethod": "CREDIT_CARD",
"creditCard": {
"card": {
"brand": "VISA",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"expiresAt": "12/2026",
"holder": {
"firstName": "Camila",
"lastName": "Silva",
"document": "12345678900",
"documentType": "CPF"
},
"billingAddress": {
"street": "Av. Paulista",
"number": "1000",
"complement": "Ap 12",
"neighborhood": "Bela Vista",
"zipCode": "01310000",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"mainInformation": "Av. Paulista, 1000",
"secondaryInformation": "Ap 12",
"latitude": -23.561684,
"longitude": -46.656139
},
"issuingCountry": "BRA"
},
"options": {
"installments": 3,
"autoCapture": true,
"captureDelay": 5,
"anticipate": 30,
"threeDSecure": true,
"retryOnFailure": true,
"noCaptureBehavior": "VOID",
"antifraud": {
"provider": "ClearSale",
"status": "APPROVED",
"scoreThreshold": 70,
"score": 85,
"riskLevel": "LOW",
"metadata": {
"ipAddress": "1.2.3.4",
"deviceFingerprint": "abc123xyz",
"customerSince": "2020-01-01",
"previousOrders": 2
}
}
},
"authorizedAt": "2025-05-31T16:30:00.000Z",
"capturedAt": "2025-05-31T16:30:00.000Z",
"authorizationCode": "A12345",
"nsu": "987654321",
"acquirer": "CIELO",
"threeDSecure": {
"enrolled": true,
"authenticated": false,
"threeDSUrl": "https://3ds.challenge.provider.com/abc123"
}
},
"status": "APPROVED"
}
]
}
]
}
🚨 Important Notes
- It is highly recommended to validate the document field for local compliance.
- 3DS authentication enhances security and helps in dispute management.
- Be sure to collect explicit customer consent for installment payments when applicable.
- Billing address can help improve authorization rates and lower fraud risks, especially internationally.
- Retry on failure can help recover transactions in case of transient declines.
✅ Summary
To process card payments with Orkestra:
- Collect card number, expiry date, and security code (CVV/CVC).
- Collect customer information (name and document).
- Use the options object to configure installments, 3DS, capture strategy, and receivables anticipation.
Orkestra handles authorization, capture, and secure transaction processing behind the scenes.