PaystationdocsPaystation

Create a charge ​

POST /v1/charges

Create a charge

POST/v1/charges

Autenticação

  • Chave públicapk_…, pode ir para o navegador
  • Chave secretask_…, só no seu servidor

Envie a chave no cabeçalho Authorization: Bearer <chave>.

Parâmetros

  • idempotency-keystring · header (uuid)obrigatório

    UUID v4, one per purchase attempt. The key is bound to the purchase: every body field but `payment.cards` must match the first request under it (`idempotency_key_reuse` otherwise). While the key holds nothing, a request under it charges the cards it carries, so their tokens must be valid when sent (a Pagar.me token is single use and lives 60s). Once the key holds an answer or a charge, that answers every request under it, whatever cards it carries: a kept answer is replayed for 24h from when it was stored (then `idempotency_key_expired`), a charge in progress is answered as it is now. Each response below says whether the key keeps it.

  • cf-turnstile-tokenstring · header

    Required for card payments with a public key, and on any key when the account enables Turnstile.

Corpo da requisição

  • offer_idstring (uuid)obrigatório
  • order_bump_idsarray of string
  • couponstringpode ser null
  • customerobject
    Mostrar campos de customer
    • namestringobrigatório
    • emailstring (email)obrigatório
    • documentstringobrigatório
    • document_typestring

      Valores: cpfcnpjpassport

    • phonestringobrigatório
    • addressobjectobrigatório
      Mostrar campos de address
      • streetstringobrigatório
      • numberstringobrigatório
      • neighborhoodstringobrigatório
      • zip_codestringobrigatório
      • complementstring
      • citystringobrigatório
      • statestringobrigatório
      • countrystring
    • custom_fieldsobjectpode ser null
  • paymentobjectobrigatório
    Mostrar campos de payment
    • methodstringobrigatório

      Valores: cardpixboleto

    • installmentsinteger
    • save_cardboolean
    • cardsarray of object
      Mostrar campos de cards
      • acquirerstringobrigatório
      • tokenstringobrigatório
    • saved_fromstring (uuid)
  • metadataobject

Resposta

201OK

  • idstring (uuid)obrigatório
  • objectstringobrigatório

    Valores: charge

  • statusstringobrigatório

    Valores: processingpendingpaidrefund_pendingrefundedchargedbackdeclined

  • amountintegerpode ser nullobrigatório

    Integer cents.

  • payment_methodstringobrigatório

    Valores: cardpixboleto

  • acquirerstringpode ser nullobrigatório
  • paymentobjectobrigatório

    Pix: `qr_code`, `expiration_at`. Boleto: `boleto_url`, `boleto_barcode`, `expiration_date`. Card: empty.

    Mostrar campos de payment
    • qr_codestring
    • expiration_atstring
    • boleto_urlstring
    • boleto_barcodestring
    • expiration_datestring
  • created_atstringpode ser nullobrigatório
  • customerobjectpode ser nullobrigatório

    Masked unless the key is secret; always masked on creation.

    Mostrar campos de customer
    • namestringpode ser nullobrigatório
    • emailstringpode ser nullobrigatório
    • documentstringpode ser nullobrigatório
    • document_typestringpode ser nullobrigatório

      Valores: cpfcnpjpassport

    • phonestringpode ser nullobrigatório
  • subscriptionstringpode ser null

    The subscription this purchase opened (`sub_…`), or `null`. Answered on creation and on `GET /v1/charges/{id}` only.

  • metadataobjectpode ser null

    The `metadata` sent on creation, or `null`. Answered on creation and to the secret key; left out of a public key's reads.

Erros

401Missing or invalid key.
402Declined (`card_declined`: every acquirer refused, or one refused for a reason the next would repeat, such as insufficient funds or suspected fraud), or no acquirer available for the cards sent (`acquirer_disabled`; on a subscription offer also when no card was sent on an acquirer a subscription can renew on). `card_declined` is kept by the key; `acquirer_disabled` leaves it free.
403Turnstile token missing (`turnstile_required`), refused (`turnstile_invalid`) or already used too many times (`turnstile_budget_exhausted`); a new challenge is needed. It leaves the key free.
404No such offer (`offer_not_found`), or no upsell for `saved_from` (`upsell_not_available`). It leaves the key free.
409The Idempotency-Key holds a request with no answer stored, started less than 2 minutes ago (`idempotency_key_in_use`), was first used with another purchase (`idempotency_key_reuse`; `payment.cards` does not count), holds an answer stored more than 24h ago (`idempotency_key_expired`), or holds an older request with no answer stored whose outcome nothing can tell (`idempotency_key_unresolved`). The last two may have charged: such a charge is listed by `GET /v1/charges` (secret key) filtered by `metadata`, and its webhook reaches the partner destination. Or the upsell was already purchased (`upsell_already_purchased`, which leaves the key free).
422The `Idempotency-Key` header is missing (`missing_idempotency_key`) or not a UUID v4 (`invalid_idempotency_key`), the body is invalid (`invalid_param`) or carries a field it does not take (`unknown_parameter`), the order was rejected (`order_rejected`), or the payment request was refused before anything was charged (`payment_rejected`: by the payment gateway, or by the acquirer — e.g. a reused or expired card token, so a new token or another card), or no saved card is usable (`saved_card_unavailable`). `order_rejected`, `payment_rejected` and an unknown `order_bump_ids` are kept by the key; the others leave it free.
429Rate limited.
500Unexpected error, or `api_unavailable`: the charge may have happened. When the charge was already in progress, the key holds it and answers it as it is now (409 `idempotency_key_in_use`, then `idempotency_key_unresolved`, while it cannot be told); when nothing was opened, the key is free; a failure while opening the transaction, before any gateway call, is kept by the key.
503The API is not available right now (`api_unavailable`): the acquirer priority could not be read or the charge ran out of time before opening (no charge was opened and the key is free), the state of the charge the key holds could not be read, or the idempotency store was unreachable (the key is as it was).

Todo erro vem no mesmo envelope: error.type, error.code, error.message e error.request_id, também devolvido no cabeçalho X-Request-Id.