> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Cobre um cartão em uma única etapa
> Autorize e capture um pagamento em uma única requisição. Use para bens digitais ou qualquer pedido que você cumpre de imediato.
export const SchemaLangNote = ({lang}) => {
const text = ({
es: "Los nombres de campos y el esquema de solicitud/respuesta que se muestran a continuación están en inglés — se generan a partir de la especificación OpenAPI. El texto explicativo de esta página está traducido.",
pt: "Os nomes dos campos e o esquema de requisição/resposta exibidos abaixo estão em inglês — são gerados a partir da especificação OpenAPI. O texto explicativo desta página está traduzido."
})[lang] || "Field names and the request/response schema shown below are in English — they are generated from the OpenAPI specification.";
return {text};
};
`POST /payment/purchase` autoriza e captura fundos em uma única ida e volta. Use quando você pode cumprir o pedido de imediato — bens digitais, assinaturas SaaS ou varejo com estoque. Para bens físicos que são enviados depois, considere [Authorize](/api-reference/authorize) + [Capture](/api-reference/capture) para reter fundos até o cumprimento sem liquidar antes da hora.
A forma completa da requisição e da resposta — cada campo de `card`/`shopper`/`amount`, os valores de `status` e o detalhe de `refusalCode`/`actionRequired`/`token` — está documentada nos painéis de parâmetros e resposta acima (gerados a partir da especificação da API).
O `id` da resposta é o UUID de pagamento do Therius — **guarde-o**, é o identificador para uma chamada posterior a [Refund](/api-reference/refund) ou [Cancel or Refund](/api-reference/cancel-or-refund). `paymentCode` (p. ex. `"PC-1234567890"`) é uma referência separada para conciliação, suporte e [Inquiry](/api-reference/inquiry) — **não** é aceito para reembolso/cancelamento.
## Exemplos
### Cobrar um cartão
```bash cURL theme={"dark"}
curl -X POST https://api.therius.io/v1/payment/purchase \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"merchantCode": "MERCHANT_001",
"orderCode": "ORDER-20240101-001",
"amount": { "currency": "USD", "value": 4999, "exponent": 2 },
"card": {
"cardData": {
"cardNumber": "4111111111111111",
"cardholderName": "Ada Lovelace",
"expiryMonth": "12",
"expiryYear": "2030",
"cvv": "123"
}
}
}'
```
```json 200 OK theme={"dark"}
{
"id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
"status": "captured",
"paymentCode": "PC-1234567890",
"orderCode": "ORDER-20240101-001",
"merchantCode": "MERCHANT_001",
"amount": { "currency": "USD", "value": 4999, "exponent": 2 },
"card": {
"cardData": { "brand": "visa", "cardNumber": "411111****1111", "type": "credit" },
"networkTransactionId": "txn_abc123"
}
}
```
**Resposta recusada**
```json theme={"dark"}
{
"status": "declined",
"paymentCode": "PC-9876543210",
"orderCode": "ORDER-20240101-002",
"merchantCode": "MERCHANT_001",
"amount": { "currency": "USD", "value": 4999, "exponent": 2 },
"refusalCode": {
"reason": "Insufficient funds",
"reasonCode": "INSUFFICIENT_FUNDS",
"recoveryAction": "switch_method"
}
}
```
`amount.value` está sempre em unidades menores. `1999` = \$19.99 para USD (exponent `2`). `5000` = ¥5000 para JPY (exponent `0`). Use sempre o campo `exponent` para determinar a posição decimal.
Se `status` for `"pending_3ds"`, redirecione o titular do cartão para `actionRequired.url` para concluir o desafio 3D Secure. Assim que ele terminar, chame [POST /payment/resume](/api-reference/resume) com o `sessionId` da resposta `pending_3ds` para continuar. Se você usa o SDK JS do Therius, chame `sdk.handleAction(result.actionRequired)` — ele trata o redirecionamento e o resume automaticamente.
## OpenAPI
````yaml POST /payment/purchase
openapi: 3.1.0
info:
title: Therius API
description: REST API for payments, subscriptions, and billing plans.
version: 1.0.0
servers:
- url: https://api.therius.io/v1
description: Production
- url: https://api-sandbox.therius.io/v1
description: Sandbox
security:
- bearerAuth: []
paths:
/payment/purchase:
post:
tags:
- Payments
summary: Charge a card in one step
operationId: purchasePayment
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- merchantCode
- orderCode
- amount
properties:
merchantCode:
type: string
description: >-
Your merchant account identifier. Validated against the
Bearer key's merchant; required if the key maps to more than
one merchant account.
orderCode:
type: string
description: >-
Your internal order reference. Must be unique per merchant —
use it to correlate Therius payments with your own records.
amount:
$ref: '#/components/schemas/Amount'
card:
$ref: '#/components/schemas/Card'
apm:
type: object
description: >-
Alternative payment method data — use instead of `card` for
APMs such as Pix, ACH or Boleto. Structure varies by method.
paymentMethod:
type: string
description: >-
Payment method code. Omit for card payments; for APMs pass
the code, e.g. `pix`, `ach`, `boleto`.
shopper:
$ref: '#/components/schemas/Shopper'
webhookUrl:
type: string
description: >-
Per-payment webhook URL override (HTTPS only). Therius posts
the final payment status here when it changes
asynchronously.
connectionCode:
type: string
description: >-
Pin this payment to a specific gateway connection. Omit to
use your routing rules.
ipAddress:
type: string
description: >-
Cardholder's IP address, passed to fraud scoring when
available.
metadata:
type: object
additionalProperties:
type: string
description: >-
Arbitrary string key/value pairs, echoed back in webhook
payloads.
responses:
'200':
description: Payment processed
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
description: >-
A UUID you generate per operation. Required in production. Retrying with
the same key returns the original response.
schema:
type: string
format: uuid
schemas:
Amount:
type: object
required:
- currency
- value
- exponent
properties:
currency:
type: string
description: >-
ISO 4217 currency code. On capture, refund and cancel it must match
the currency of the original payment.
example: USD
value:
type: integer
description: >-
Amount in minor units (cents, pence, etc.). `4999` = $49.99 for USD
(exponent 2); `5000` = ¥5000 for JPY (exponent 0). On capture it
must not exceed the authorized value; on refund the cumulative total
across refunds must not exceed the captured amount.
example: 4999
exponent:
type: integer
description: >-
Number of decimal places for the currency — `2` for USD/EUR, `0` for
JPY. Determines where the decimal point sits in `value`.
example: 2
Card:
description: >-
Card input for one-off payments: exactly one instrument (`cardData` /
`nonceData` / `tokenData`) plus optional stored-credential and
installment modifiers.
allOf:
- $ref: '#/components/schemas/CardInstrument'
- type: object
properties:
cardOnFile:
$ref: '#/components/schemas/CardOnFile'
instalments:
type: integer
description: Number of issuer installments (LATAM markets). Defaults to 1.
networkTransactionId:
type: string
description: >-
Scheme mandate reference from the original CIT. Cite it on
merchant-initiated stored-credential charges.
networkReferenceId:
type: string
description: >-
Mastercard TLID (or scheme equivalent) from the original CIT,
sent alongside `networkTransactionId`.
Shopper:
type: object
description: >-
Shopper information. Required when tokenizing a card
(`card..tokenize: true`).
properties:
id:
type: string
description: >-
Your internal shopper ID. Used to associate saved tokens with a
customer.
email:
type: string
format: email
description: Shopper's email address.
name:
type: string
description: Shopper's full name.
PaymentResponse:
type: object
properties:
id:
type: string
format: uuid
description: >-
The Therius payment id. Returned by `POST /payment/authorization`
and `POST /payment/purchase`; use it as the `{id}` path segment for
capture, refund, cancel and cancel_or_refund.
example: 9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e
status:
$ref: '#/components/schemas/PaymentStatus'
paymentCode:
type: string
description: >-
Therius receipt ID, for reconciliation, support and Inquiry. NOT the
handle for capture/refund/cancel — use `id` for that.
example: PC-1234567890
orderCode:
type: string
description: Your `orderCode`, echoed back.
merchantCode:
type: string
description: Your `merchantCode`, echoed back.
autorizationCode:
type: string
description: >-
Issuer authorization code on an approved payment. The field name is
misspelled on the wire (no `h`) - this is intentional and stable.
paymentMethod:
type: string
description: Payment method used, e.g. `card`, `pix`, `ach`.
connectionCode:
type: string
description: Code of the gateway connection that processed the payment.
connectionName:
type: string
description: Display name of the gateway connection that processed the payment.
amount:
$ref: '#/components/schemas/Amount'
card:
type: object
description: >-
Card details from the response: masked PAN, brand, type, and the
network transaction/reference IDs to cite on future MIT charges.
apm:
type: object
description: >-
Alternative-payment-method details (redirect URL, QR code, barcode)
when `paymentMethod` is an APM.
token:
type: object
description: 'Present when the card was tokenized (`tokenize: true`).'
properties:
id:
type: string
description: Token ID to use in future `tokenData` charges.
expirationDate:
type: string
description: Token expiry date.
actionRequired:
$ref: '#/components/schemas/ActionRequired'
refusalCode:
$ref: '#/components/schemas/RefusalCode'
CardInstrument:
description: >-
The payment instrument. Provide exactly ONE of `cardData`, `nonceData`,
or `tokenData` — they are interchangeable alternatives, not fields to
send together. `cardData` carries a raw PAN and requires your server to
be PCI DSS compliant; `nonceData` is a single-use nonce from the Therius
JS SDK; `tokenData` reuses a stored `vt_...` vault token.
oneOf:
- title: Raw card (PCI DSS)
type: object
required:
- cardData
properties:
cardData:
$ref: '#/components/schemas/CardData'
- title: SDK nonce
type: object
required:
- nonceData
properties:
nonceData:
$ref: '#/components/schemas/NonceData'
- title: Vault token
type: object
required:
- tokenData
properties:
tokenData:
$ref: '#/components/schemas/TokenData'
CardOnFile:
type: object
description: >-
Stored-credential (MIT/CIT) framework metadata for one-off payments.
Optional — Therius derives it from context when omitted. Not accepted on
subscription endpoints.
properties:
usage:
type: string
description: >-
Whether this charge establishes the stored-credential mandate
(`first`) or draws against an existing one (`subsequent`). Always
required alongside the other cardOnFile fields.
enum:
- first
- subsequent
initiatedBy:
type: string
description: >-
Who triggered this specific charge: the shopper live at checkout
(`cardholder`) or your billing engine unattended (`merchant`).
enum:
- cardholder
- merchant
type:
type: string
description: >-
The schedule shape of the mandate — independent of
`exceptionReason`. `recurring`: fixed-interval, usually fixed-amount
(subscriptions, membership dues). `installment`: a pre-agreed split
of one purchase into N charges. `unscheduled`: authorized in advance
but triggered by a merchant-defined event, including cards saved for
future use when the eventual charge pattern isn't known yet.
enum:
- recurring
- installment
- unscheduled
exceptionReason:
type: string
description: >-
Optional, MIT-only, and orthogonal to `type` — only set when this
particular charge falls into one of the scheme-defined exception
categories. `resubmission`: retrying a prior soft-declined charge
(insufficient funds, do-not-honor) for the same amount.
`incremental`: an authorization top-up on an existing mandate (e.g.
a hotel folio adds a room-service charge). `reauthorization`: a
fresh authorization because the original one expired before capture
(goods not yet shipped). `delayed_charge`: the final amount differs
from an earlier estimate/hold (car-rental extra mileage, a
restaurant tip). `no_show`: the cardholder didn't show up for a
reserved, guaranteed booking.
enum:
- resubmission
- incremental
- reauthorization
- delayed_charge
- no_show
PaymentStatus:
type: string
enum:
- captured
- authorized
- declined
- pending_3ds
- pending_action
- failed
- cancelled
- refunded
description: >-
`captured` - funds settled; `authorized` - funds reserved, call capture
to settle; `declined` - issuer declined, see `refusalCode`;
`pending_3ds` - a 3DS challenge is required, see `actionRequired`;
`pending_action` - an external action (redirect, voucher) is required,
see `actionRequired`; `failed` - processing error unrelated to the
issuer; `cancelled` - authorization voided; `refunded` - captured funds
returned.
ActionRequired:
type: object
description: >-
Present when `status` is `pending_3ds` or `pending_action`. Describes
what the cardholder must do next — with the Therius JS SDK, pass the
whole object to `sdk.handleAction()`.
properties:
type:
type: string
description: Action type, e.g. `redirect`, `barcode`.
url:
type: string
description: >-
URL to send the cardholder to for a 3DS challenge or external APM
flow.
paymentCode:
type: string
description: Therius payment code tied to this pending action.
barcode:
type: string
description: Barcode value for APMs that require it (e.g. Boleto).
params:
type: object
description: Additional parameters required to complete the action.
RefusalCode:
type: object
description: >-
Present when `status` is `declined`. See the Declined Payments concept
page for the full code table and how to react to each `recoveryAction`.
properties:
reason:
type: string
description: Human-readable meaning of `reasonCode`.
example: Insufficient funds
reasonCode:
type: string
description: >-
Normalized ISO 8583 decline code. Every provider decline is mapped
to this set, so handling logic is provider-independent. Full table
with meanings on the Declined Payments concept page.
example: '51'
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
- '11'
- '12'
- '13'
- '14'
- '15'
- '16'
- '17'
- '19'
- '20'
- '21'
- '22'
- '25'
- '28'
- '30'
- '41'
- '43'
- '46'
- '51'
- '52'
- '53'
- '54'
- '55'
- '57'
- '58'
- '59'
- '61'
- '62'
- '63'
- '65'
- '68'
- '75'
- '76'
- '77'
- '78'
- '80'
- '81'
- '82'
- '83'
- '85'
- '91'
- '92'
- '93'
- '94'
- '95'
- '96'
- B1
- N0
- N3
- N4
- N7
- P2
- P5
- P6
- Q1
- R0
- R1
- R3
- XA
- XD
- Z3
originalReason:
type: string
description: >-
Raw message the underlying provider returned, before normalization.
Diagnostic only — format is not stable across providers.
originalReasonCode:
type: string
description: >-
Raw code the underlying provider returned, before normalization.
Diagnostic only — format varies by provider.
recoveryAction:
type: string
description: >-
What the checkout should do next: `retry` (transient/technical —
same card may be retried once), `switch_method` (this card will not
work — prompt for another method), `terminal` (hard block — do not
retry or offer an alternative).
enum:
- retry
- switch_method
- terminal
CardData:
type: object
description: >-
Raw card details. Only if your server is PCI DSS compliant to handle raw
PANs — otherwise collect the card with the Therius JS SDK and send
`nonceData`.
properties:
cardNumber:
type: string
description: Full PAN, digits only.
example: '4111111111111111'
cardholderName:
type: string
description: Name as it appears on the card.
example: Ada Lovelace
expiryMonth:
type: string
description: Two-digit expiry month, e.g. `12`.
example: '12'
expiryYear:
type: string
description: Four-digit expiry year, e.g. `2030`.
example: '2030'
cvv:
type: string
description: Card verification value (3 or 4 digits).
example: '123'
tokenize:
type: boolean
description: >-
Set to `true` to save this card as a reusable token. Requires
`shopper.id` in the request.
cardAddress:
$ref: '#/components/schemas/CardAddress'
documentNumber:
type: string
description: Cardholder tax/document ID, required by some LATAM acquirers.
typeOverride:
type: string
description: Override the detected card type, e.g. `debit`.
NonceData:
type: object
description: >-
Single-use nonce from the Therius JS SDK — no card data touches your
server. Nonces are single-use and expire after a short window.
properties:
nonce:
type: string
description: The nonce string returned by the SDK.
cardholderName:
type: string
description: Cardholder name.
cardAddress:
$ref: '#/components/schemas/CardAddress'
tokenize:
type: boolean
description: >-
Save the card as a token after payment. Requires `shopper.id` in the
request.
typeOverride:
type: string
description: Override the detected card type.
TokenData:
type: object
description: A `vt_...` vault token for a card the shopper previously tokenized.
properties:
token:
type: string
description: Token ID returned from a prior tokenization.
cvv:
type: string
description: CVV, if re-collection is required by the acquirer.
cardAddress:
$ref: '#/components/schemas/CardAddress'
CardAddress:
type: object
properties:
line1:
type: string
line2:
type: string
city:
type: string
state:
type: string
postalCode:
type: string
country:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
prv_sandbox_xxx` (sandbox).
````