Skip to main content
POST
Create a payment

Authorizations

​
Authorization
string
header
required

A secret key, sk_test_... or sk_live_...; a publishable key (pk_...) on the browser routes only

Body

application/json
​
amount
integer
required

In the smallest unit of the currency.

Example:

12550

​
currency
enum<string>
required
Available options:
USD,
CAD
Example:

"USD"

​
payment_method
string

A payment method of yours that is active. A one-time method is spent by this charge. Send this or payment_method_session.

Required string length: 1 - 64
Example:

"pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf"

​
payment_method_session
string

A payment method session your page confirmed with Payra Elements, charged in this same call: the payment method is made from it (one-time for a card) and comes back as payment_method. Send this or payment_method.

Required string length: 1 - 64
​
terminal
string<uuid>

A terminal assigned to your account (GET /v1/terminals): the amount is sent to it and the customer presents the card there. Send this, payment_method or payment_method_session. Needs customer, USD, and no return_url or save_payment_method.

​
description
string
Required string length: 1 - 500
Example:

"Invoice INV-1042"

​
reference
string

Your own reference for this charge, such as an order or invoice number; shown on the payment.

Required string length: 1 - 100
Example:

"INV-1042"

​
customer
string<uuid>

Optional for a payment method, which must be saved on it when given; required with terminal.

​
return_url
string<uri>

Where the customer comes back to after 3-D Secure, with ?payment=pay_… appended. With it, a card charge the bank wants to verify answers requires_action with a redirect next_action: a Payra page, or the bank's, that brings the customer back here. Without it, a card confirmed with Payra Elements is verified on your page (three_ds_fingerprint, three_ds_challenge, which handleNextAction runs). Must be https (or http://localhost with a sandbox key). No effect on a bank debit, or while 3-D Secure is not enabled for your workspace.

Maximum string length: 2048
Example:

"https://shop.example.com/orders/1042/paid"

​
save_payment_method
boolean

Keep this one-time card on its customer once the charge succeeds. The charge proves the card, so Payra runs no separate verification where the processor allows it. The payment method becomes saved, same id; when the customer already had this card saved in the same currency, the payment names that saved method instead and the card is not saved twice. Needs a session created with customer and a billing postal code. Sending it states that the customer agreed to keep the card on file. After 3-D Secure, the card is kept once the payment succeeds. Ignored for a method that is already saved.

Example:

true

​
line_items
object[]

The order behind amount, 1 to 100 lines. Each line comes to quantity × unit_amount, rounded half up to the cent. The lines, plus amount_details.shipping and amount_details.tax, minus amount_details.discount, must come to amount.

Required array length: 1 - 100 elements
​
amount_details
object

Shipping, tax and discount around line_items, in the smallest unit of the currency. Needs line_items.

Response

The payment

​
object
enum<string>
required
Available options:
payment
​
id
string
required
Example:

"pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf"

​
status
enum<string>
required

processing until the processor answers, and, on a bank debit, until it settles, that is until the processor sends it to the bank in its next batch; authorized when it approved but has not captured; succeeded once a card is captured or a bank debit has settled, which does not make a bank debit final (see returned); failed when it refused (the create then answers 402 and this object stays readable); canceled after a void, a cancel, or a terminal payment nobody paid within five minutes (see cancellation_reason); returned when the money came back after success (a bank return or a chargeback, see failure); requires_action while the customer has to pass 3-D Secure, as next_action says; it then moves to succeeded or failed.

Available options:
processing,
requires_action,
authorized,
succeeded,
failed,
canceled,
returned
Example:

"succeeded"

​
amount
integer
required

In the smallest unit of the currency (cents).

Example:

12550

​
currency
enum<string>
required
Available options:
USD,
CAD
Example:

"USD"

​
payment_method
string | null
required

The payment method charged; null on a terminal payment, where the customer presented the card on the terminal.

Example:

"pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf"

​
customer
string<uuid> | null
required
Example:

null

​
description
string | null
required
Example:

"Invoice INV-1042"

​
reference
string | null
required

Your reference, as you sent it.

Example:

"INV-1042"

​
card
object | null
required

Set when payment_method_type is card.

​
failure
object | null
required

Set when status is failed or returned: why, in a fixed vocabulary. card_declined, insufficient_funds, authentication_failed, invalid_payment_method and duplicate_transaction are the processor refusing the card; ach_returned, acss_returned and chargeback are money coming back after success; processing_error is a fault on the way to the processor or in the request, safe to retry later; a refusal in words Payra cannot classify reads card_declined. message is Payra's own sentence for the reason, or for the code when there is none; the processor's own text is never relayed.

​
next_action
object | null
required

Set while status is requires_action, for 3-D Secure. redirect, on a charge created with return_url: send the customer to url, a Payra page or the bank's; they come back to your return_url. three_ds_fingerprint and three_ds_challenge, on a charge without it: url is a Payra page your page runs in a frame, hidden for the fingerprint and in a modal for the challenge; Payra Elements does that in handleNextAction, and the payment then turns succeeded or failed without leaving the page. Null otherwise.

Example:

null

​
livemode
boolean
required
Example:

false

​
created_at
string<date-time>
required
Example:

"2026-09-18T20:00:00.000Z"

​
succeeded_at
string<date-time> | null
required

When the card was captured, or the bank debit settled.

Example:

"2026-09-18T20:00:01.312Z"

​
amount_refunded
integer
default:0

How much of amount has been refunded so far, counting refunds that succeeded, wherever they were made. status stays succeeded; GET /v1/refunds?payment= lists them.

Example:

0

​
payment_method_type
enum<string>
default:card

us_bank_account for a US bank debit (ACH), acss_debit for a Canadian one (EFT), card_present for a terminal payment. More values may be added: treat one you do not know as a card.

Available options:
card,
us_bank_account,
acss_debit,
card_present
Example:

"card"

​
terminal
string | null

The terminal a terminal payment was sent to (GET /v1/terminals/{id}); null on any other payment.

Example:

null

​
terminal_progress
object | null

Where a terminal payment still processing is on its terminal, read from the terminal when you retrieve the payment (GET /v1/payments/{id}). Null on every other answer (the create, lists, events), on a payment that is not open on a terminal, and whenever the terminal did not say: keep showing the last one you read.

Example:

null

​
line_items
object[] | null

The order behind amount, as you sent it (or as the checkout session it was paid on had it); null when there was none.

Example:

null

​
amount_details
object | null

Shipping, tax and discount around line_items; null when none were sent.

Example:

null

​
us_bank_account
object | null

Set when payment_method_type is us_bank_account.

Example:

null

​
acss_debit
object | null

Set when payment_method_type is acss_debit.

Example:

null

​
cancellation_reason
enum<string> | null

Set when status is canceled: requested (canceled on request before the card was presented, through the API or in RevOS), expired (no card was presented within five minutes) or voided (voided before the batch, in RevOS or by a full refund). More values may be added.

Available options:
requested,
expired,
voided
Example:

null

​
processing_fee
object | null

What the card charge costs the merchant to process: interchange, scheme fees and processor markup. amount is in the smallest unit of currency, the payment's currency; basis says whether it is Payra's estimate from the card's first six digits or the processor's actual fee. Sandbox preview for now: set on a sandbox card payment in USD of a workspace with the preview enabled, and null otherwise, on a failed or canceled payment, a bank debit, a terminal payment and every live payment. See Processing fee in the API guide for the value each test card gives.

Example: