Create a charge

Creates a Pix charge and returns the copy-and-paste code and QR image to show the payer.

POST/charges

Headers

AuthorizationBasic

Required

client_id:api_key, see Authentication

Content-Typestring

Required

application/json

Idempotency-Keystring

Recommended. Repeating a key returns the charge it created instead of a new one. Without it, the same reference with the same amount also returns the existing charge

Armhed-Operation-Tokenstring

Optional token with scope charges:create

Body

amountinteger

Required

Amount in cents, greater than 0 and within your account's per-charge limit

referencestring

Your order id (up to 100 characters). Returned on the charge and in every webhook event

customerobject

Who you are charging: name, email, phone, document (CPF or CNPJ, digits only). Optional; missing fields are filled with placeholders

descriptionstring

What is being paid for (up to 140 characters)

expires_in_daysinteger

1 to 30, default 1. Some settlement routes cap QR validity at the bank to 1 hour; pix.expires_at always shows the effective value we know of

metadataobject

Any JSON you want stored with the charge

Requestjson

{
  "amount": 4990,
  "reference": "order-1042",
  "description": "Annual plan",
  "customer": {
    "name": "Ana Souza",
    "email": "ana@example.com",
    "phone": "11987654321",
    "document": "24577481600"
  },
  "expires_in_days": 1,
  "metadata": { "cart": "c_88" }
}

When customer or any of its fields is missing, it is stored as name Cliente, email nao-informado@armhed.lat, phone and document 00000000000. Some banks validate the payer document, so send the real one when you have it. The person who actually pays may differ from the customer; their name and document arrive in payer once the charge is paid.

Response

201 Created with the charge object.

201 Createdjson

{
  "object": "charge",
  "id": "6dcf2aee0d6148e1a12b78db78",
  "reference": "order-1042",
  "status": "pending",
  "amount": 4990,
  "refunded_amount": 0,
  "fee": null,
  "net_amount": null,
  "currency": "BRL",
  "pix": {
    "copy_paste": "00020126580014br.gov.bcb.pix...6304ABCD",
    "qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "expires_at": "2026-11-01T12:00:00Z",
    "end_to_end_id": null
  },
  "customer": {
    "name": "Ana Souza",
    "email": "ana@example.com",
    "phone": "11987654321",
    "document": "24577481600"
  },
  "payer": { "name": null, "document": null },
  "failure_reason": null,
  "created_at": "2026-10-31T12:00:00Z",
  "paid_at": null,
  "canceled_at": null,
  "refunded_at": null
}

The charge object

idstring

Charge id. Store it to retrieve the charge and match webhook events

referencestring

Your reference

statusstring

pending, paid, failed, canceled or refunded

amount / refunded_amountinteger

Cents

fee / net_amountinteger

Cents. Filled once the charge is settled

pix.copy_pastestring

Pix copy-and-paste code

pix.qr_codestring

QR image as a data URL. Only returned on creation; build the QR from copy_paste afterwards

pix.end_to_end_idstring

Central Bank transaction id, once paid

payerobject

Name and document of whoever actually paid

failure_reasonstring

Why the charge failed, when status is failed

Errors

400 Bad Requestjson

{
  "error": {
    "type": "invalid_request",
    "message": "Valor acima do limite permitido. O valor máximo por cobrança PIX é R$ 1,500.00.",
    "request_id": "0HN7KQ4F1V2C3:00000004"
  }
}

Example

Node.jsjavascript

const res = await fetch("https://api.armhed.lat/charges", {
  method: "POST",
  headers: {
    Authorization: "Basic " + Buffer.from(`${CLIENT_ID}:${API_KEY}`).toString("base64"),
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}`,
  },
  body: JSON.stringify({ amount: order.totalCents, reference: `order-${order.id}` }),
})
const charge = await res.json()
if (!res.ok) throw new Error(charge.error.message)
// show charge.pix.copy_paste / charge.pix.qr_code to the payer