Overview
Orkestra supports processing debit card payments, enabling merchants to accept transactions securely and efficiently.
Debit card payments are authorized and captured in real-time and typically settle faster, ensuring quick fund availability.
Merchants must explicitly ask the customer whether they are using a Credit Card (CREDIT_CARD) or Debit Card (DEBIT_CARD), since card type identification via PAN is not automatically possible in some regions (e.g. Brazil).
To create a debit card payment, set the paymentMethod to DEBIT_CARD in the transaction and provide the required card details.
📝 Minimum Required Fields for Debit Card Payment
When creating an Order for a debit 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 DEBIT_CARD. |
charges[].transactions[].debitCard.card.number | String | Card number (PAN). |
charges[].transactions[].debitCard.card.expiresAt | String | Expiry date in MM/YYYY format. |
charges[].transactions[].debitCard.card.securityCode | String | Card Verification Value (CVV / CVC). |
⚙️ Optional Debit Card Fields
| Field | Type | Description |
|---|---|---|
charges[].transactions[].debitCard.card.holder.firstName | String | Cardholder’s first name (if different from customer). |
charges[].transactions[].debitCard.card.holder.lastName | String | Cardholder’s last name. |
charges[].transactions[].debitCard.card.holder.documentType | Enum | Cardholder’s document type. |
charges[].transactions[].debitCard.card.holder.document | String | Cardholder’s document number. |
charges[].transactions[].debitCard.card.billingAddress | Object | Billing address (same structure as livingAddress). |
charges[].transactions[].debitCard.card.issuingCountry | Enum (ISO Alpha-3) | Country code of card issuing country (e.g., BRA, USA, ARG). |
📦 options Object
While installments are not supported for debit cards, you can still configure other processing options:
| Field | Type | Description |
|---|---|---|
charges[].transactions[].debitCard.card.holder.firstName | String | Cardholder’s first name (if different from customer). |
charges[].transactions[].debitCard.card.holder.lastName | String | Cardholder’s last name. |
charges[].transactions[].debitCard.card.holder.documentType | Enum | Cardholder’s document type. |
charges[].transactions[].debitCard.card.holder.document | String | Cardholder’s document number. |
charges[].transactions[].debitCard.card.billingAddress | Object | Billing address (same structure as livingAddress). |
charges[].transactions[].debitCard.card.issuingCountry | Enum (ISO Alpha-3) | Country code of card issuing country (e.g., BRA, USA, ARG). |
🆔 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: Debit Card Payment Request
{
"merchantOrderId": "order-67890",
"softDescriptor": "Orkestra Store",
"amount": 2000,
"currency": "BRL",
"allowsThirdPartyPayments": false,
"charges": [
{
"customer": {
"firstName": "Lucas",
"lastName": "Oliveira",
"document": "98765432100",
"documentType": "CPF"
},
"transactions": [
{
"paymentMethod": "DEBIT_CARD",
"debitCard": {
"card": {
"number": "4111111111111111",
"expiresAt": "06/2027",
"securityCode": "456",
"holder": {
"firstName": "Lucas",
"lastName": "Oliveira",
"document": "98765432100",
"documentType": "CPF"
},
"billingAddress": {
"street": "Rua das Flores",
"number": "200",
"complement": "Apto 5",
"neighborhood": "Jardim América",
"zipCode": "01454000",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"mainInformation": "Rua das Flores, 200",
"secondaryInformation": "Apto 5",
"latitude": -23.563210,
"longitude": -46.654250
},
"issuingCountry": "BRA"
},
"options": {
"autoCapture": true,
"anticipate": 5,
"threeDSecure": true,
"retryOnFailure": true,
"captureDelay": 2,
"noCaptureBehavior": "VOID",
"antifraud": {
"provider": "ClearSale",
"scoreThreshold": 75,
"metadata": {
"ipAddress": "1.2.3.5",
"deviceFingerprint": "xyz789abc",
"customerSince": "2021-05-01",
"previousOrders": 3
}
}
}
}
}
]
}
]
}
🔁 Payment Flow Overview
-
You create an order with paymentMethod set to DEBIT_CARD.
-
Orkestra processes the card authorization.
-
Capture is performed immediately if autoCapture is enabled.
-
3DS authentication is enforced when configured.
-
Payment confirmation is sent via webhook.
📦 Example: Debit Card Payment Response
{
"id": 987657,
"merchantOrderId": "order-67890",
"softDescriptor": "Orkestra Store",
"amount": 2000,
"currency": "BRL",
"status": "PAID",
"allowsThirdPartyPayments": false,
"charges": [
{
"id": 123457,
"amount": 2000,
"status": "PAID",
"customer": {
"firstName": "Lucas",
"lastName": "Oliveira",
"document": "98765432100",
"documentType": "CPF"
},
"transactions": [
{
"id": 789124,
"amount": 2000,
"paymentMethod": "DEBIT_CARD",
"debitCard": {
"card": {
"brand": "VISA",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"expiresAt": "06/2027",
"holder": {
"firstName": "Lucas",
"lastName": "Oliveira",
"document": "98765432100",
"documentType": "CPF"
},
"billingAddress": {
"street": "Rua das Flores",
"number": "200",
"complement": "Apto 5",
"neighborhood": "Jardim América",
"zipCode": "01454000",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"mainInformation": "Rua das Flores, 200",
"secondaryInformation": "Apto 5",
"latitude": -23.563210,
"longitude": -46.654250
},
"issuingCountry": "BRA"
},
"options": {
"autoCapture": true,
"captureDelay": 2,
"anticipate": 5,
"threeDSecure": true,
"retryOnFailure": true,
"noCaptureBehavior": "VOID",
"antifraud": {
"provider": "ClearSale",
"status": "APPROVED",
"scoreThreshold": 75,
"score": 88,
"riskLevel": "LOW",
"metadata": {
"ipAddress": "1.2.3.5",
"deviceFingerprint": "xyz789abc",
"customerSince": "2021-05-01",
"previousOrders": 3
}
}
},
"authorizedAt": "2025-05-31T17:00:00.000Z",
"capturedAt": "2025-05-31T17:00:00.000Z",
"authorizationCode": "B67890",
"nsu": "987654322",
"acquirer": "CIELO",
"threeDSecure": {
"enrolled": true,
"authenticated": true
}
},
"status": "APPROVED"
}
]
}
]
}
🚨 Important Notes
-
Debit card transactions settle immediately after capture — no installments are supported.
-
Document validation improves authorization success and compliance.
-
3DS can reduce fraud and chargeback rates.
-
Retry on failure can recover transactions rejected for transient reasons.
-
Billing address information can help increase authorization rates and minimize fraud risks.
✅ Summary
To process debit card payments with Orkestra:
-
Collect card number, expiry date, and security code (CVV/CVC).
-
Collect customer and cardholder information.
-
Configure fraud prevention and capture behavior using the options object.
Orkestra ensures secure and efficient debit card payment processing.