Skip to main content
POST
/
api
/
v1
/
payments
Process a new payment request
curl --request POST \
  --url http://localhost:7701/api/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "merchant_order_id": "ORD-2026-12345",
  "amount": 15000,
  "currency": "BRL",
  "payment_method": "card",
  "customer": {
    "token": "cus_token_abc123",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "document": "12345678909",
    "phone": "11912345678"
  },
  "gateway_first_try": "pagarme",
  "card": {
    "token": "card_tok_xyz",
    "number": "4111111111111111",
    "cvv": "123",
    "expiration_month": "12",
    "expiration_year": "2028",
    "holder": "JOHN DOE",
    "holder_document": "12345678909",
    "holder_birthdate": "1990-05-20",
    "holder_phone": "11912345678",
    "installments": 1,
    "save_card": false,
    "sdk_tokens": {}
  },
  "billing_address": {
    "street": "Rua das Flores",
    "number": "123",
    "neighborhood": "Centro",
    "zip_code": "01310100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "splits": [
    {
      "subaccount_id": "sub_abc123",
      "amount": 5000
    }
  ]
}
'
{
  "status": "approved",
  "transaction_id": "01hvxyz...",
  "amount": 15000,
  "message": "Payment approved.",
  "attempts": 1,
  "payment_method": "card",
  "merchant_order_id": "ORD-2026-12345",
  "idempotency_key": "order-abc-123",
  "plugtopay_request_time": "0.05s",
  "total_request_time": "0.8s",
  "gateways_request_time": "0.75s",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "transactions": [
    {}
  ],
  "customer": {},
  "webhook": {},
  "card": {
    "response_code": "<string>",
    "soft_descriptor": "<string>",
    "authorization_nsu": "<string>",
    "gateway_message": "<string>"
  }
}

Authorizations

​
X-API-Key
string
header
required

Company API key. Send in the X-API-Key header.

Body

application/json
​
merchant_order_id
string
required

Your internal order reference (1–100 chars).

Example:

"ORD-2026-12345"

​
amount
integer
required

Amount in cents (R$1,00 minimum = 100)

Example:

15000

​
currency
string
required

3-letter ISO currency code.

Example:

"BRL"

​
payment_method
enum<string>
required
Available options:
card,
pix,
billet
Example:

"card"

​
customer
object
required

Identify by token (existing customer) or by name + email + document (new customer).

​
gateway_first_try
enum<string> | null

Gateway slug to attempt first. Falls back to routing rules if not set or gateway not enabled.

Available options:
pagarme,
picpay,
safe2pay,
pagbank,
stripe,
asaas,
erede
Example:

"pagarme"

​
card
object

Required when payment_method is card. Provide either token/sdk_tokens (vault) or raw card fields.

​
billing_address
object

Required when no card.token is provided.

​
splits
object[] | null

Optional split rules. Each entry directs a portion of the amount to a sub-account.

Response

Payment processed successfully

​
status
enum<string>
Available options:
approved,
failed,
pending
Example:

"approved"

​
transaction_id
string
Example:

"01hvxyz..."

​
amount
integer
Example:

15000

​
message
string
Example:

"Payment approved."

​
attempts
integer
Example:

1

​
payment_method
string
Example:

"card"

​
merchant_order_id
string | null
Example:

"ORD-2026-12345"

​
idempotency_key
string | null
Example:

"order-abc-123"

​
plugtopay_request_time
string | null
Example:

"0.05s"

​
total_request_time
string | null
Example:

"0.8s"

​
gateways_request_time
string | null
Example:

"0.75s"

​
created_at
string<date-time> | null
​
updated_at
string<date-time> | null
​
transactions
object[]
​
customer
object
​
webhook
object
​
card
object

Present when payment_method is card and status is not processing.