curl --request POST \
--url https://api-dashboard.payra.com/v1/payment-methods \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"session": "pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd"
}
'{
"object": "payment_method",
"id": "pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf",
"type": "card",
"usage": "saved",
"status": "active",
"customer": null,
"session": "pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd",
"card": {
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2030,
"funding": "credit",
"wallet": null
},
"us_bank_account": null,
"acss_debit": null,
"billing_details": {
"name": "Ada Lovelace",
"postal_code": "94110"
},
"next_action": null,
"failure": null,
"livemode": false,
"expires_at": null,
"created_at": "2026-09-18T14:00:00.000Z"
}{
"object": "payment_method",
"id": "pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf",
"type": "card",
"usage": "saved",
"status": "active",
"customer": null,
"session": "pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd",
"card": {
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2030,
"funding": "credit",
"wallet": null
},
"us_bank_account": null,
"acss_debit": null,
"billing_details": {
"name": "Ada Lovelace",
"postal_code": "94110"
},
"next_action": null,
"failure": null,
"livemode": false,
"expires_at": null,
"created_at": "2026-09-18T14:00:00.000Z"
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}Create a payment method
Turns a succeeded payment method session into a payment method your server can charge. When the session named a customer, the card or bank account is verified with the processor and saved on their file (usage: saved), a bank account together with the standing ACH authorization its holder accepted (a Canadian account with its pre-authorized debit agreement), unless you send usage: one_time for a card the cardholder chose not to keep; otherwise it can be charged once, soon (usage: one_time). A card the customer already has saved in the same currency is not saved twice: its saved payment method is returned with 200 instead, with the new expiry, name or postal code if they changed. The tokenized details never appear in the response.
On a workspace Payra enabled it for, your server can send a US bank account it already holds instead of a session: the numbers in us_bank_account and your attestation that the account holder authorized the debit in ach_authorization. Payra puts the numbers in its vault, records the authorization in your words, then saves the account on customer or keeps it for one debit of amount, as it would after Payra Elements. That request needs an Idempotency-Key. After bank_account_verification_failed, send corrected details with a new key.
On a workspace that runs 3-D Secure, the cardholder’s bank can authenticate a card before it is saved when you send use_payra_js (your page runs the step with payra.handleNextAction) or return_url (your server sends the cardholder to Payra’s page). The method then answers 201 with status: requires_action and a next_action, and turns active once the bank authenticated the card and it is saved, or failed when nothing was saved; read it again before you charge it. A bank that refuses at once answers 402 card_authentication_failed and saves nothing. A card the customer already has saved, collected again with a new expiry, name or postal code, makes no second method: the answer is 200 with its saved method and a next_action. That method stays active and can be charged meanwhile; it takes the new details once the bank authenticated the card, and keeps the ones it has if it did not. Without either parameter, the card is saved without that step.
curl --request POST \
--url https://api-dashboard.payra.com/v1/payment-methods \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"session": "pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd"
}
'{
"object": "payment_method",
"id": "pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf",
"type": "card",
"usage": "saved",
"status": "active",
"customer": null,
"session": "pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd",
"card": {
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2030,
"funding": "credit",
"wallet": null
},
"us_bank_account": null,
"acss_debit": null,
"billing_details": {
"name": "Ada Lovelace",
"postal_code": "94110"
},
"next_action": null,
"failure": null,
"livemode": false,
"expires_at": null,
"created_at": "2026-09-18T14:00:00.000Z"
}{
"object": "payment_method",
"id": "pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf",
"type": "card",
"usage": "saved",
"status": "active",
"customer": null,
"session": "pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd",
"card": {
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2030,
"funding": "credit",
"wallet": null
},
"us_bank_account": null,
"acss_debit": null,
"billing_details": {
"name": "Ada Lovelace",
"postal_code": "94110"
},
"next_action": null,
"failure": null,
"livemode": false,
"expires_at": null,
"created_at": "2026-09-18T14:00:00.000Z"
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"request_id": "<string>",
"param": "<string>"
}
}Authorizations
A secret key, sk_test_... or sk_live_...; a publishable key (pk_...) on the browser routes only
Body
A session of yours that has succeeded. Each session creates one payment method. Send this or us_bank_account.
1 - 64"pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd"
Required, and true, when a card session named a customer and the card is saved: your attestation that the cardholder agreed to keep the card on file. Not used for a bank account: the account holder accepted the ACH authorization, or the pre-authorized debit agreement on a Canadian account, in Payra Elements. Leave it out with us_bank_account, where ach_authorization is your attestation.
true
Leave it out and the session decides: saved when it named a customer, one_time when it did not. Send one_time for a card collected on a session with a customer when the cardholder chose not to keep it: it is charged once and not saved, and its payment is still filed on the customer. So your page can bind the session to a signed-in buyer before they choose. saved needs a customer on the session; a bank account follows its session only. Leave it out with us_bank_account, where customer decides.
saved, one_time "one_time"
Where the cardholder comes back after their bank's 3-D Secure step, with ?payment_method=pm_… appended, when your server sends them there. With it, a card the bank wants to authenticate before it is saved answers requires_action with a redirect next_action, a Payra page. Send this or use_payra_js to have the bank authenticate the card; without either the card is saved without that step, as before. Must be https (or http://localhost with a sandbox key). No effect on a one-time card, or while 3-D Secure is not enabled for your workspace.
2048true when your page runs the bank's 3-D Secure step itself, with Payra Elements: a card the bank wants to authenticate before it is saved answers requires_action with a three_ds_fingerprint or three_ds_challenge next_action, which payra.handleNextAction(paymentMethod) runs without leaving the page. Send this or return_url, not both.
A US bank account your server already holds, sent instead of a session. Once the request passes its checks, Payra puts the numbers in its vault and keeps only the token and the last four digits. Only on a workspace Payra enabled it for.
Show child attributes
Show child attributes
Your attestation that the account holder authorized the debit, required with us_bank_account. Payra records it in your words of the ACH authorization (one debit of amount, or a standing authorization with customer), never as the account holder accepting it in Payra.
Show child attributes
Show child attributes
With us_bank_account: the customer to save the account on, under a standing authorization (usage: saved). Leave it out for a one-time debit of amount.
With us_bank_account and no customer: the one debit the account holder authorized, in cents. The payment must be for exactly this amount.
With amount. A US bank account is debited in USD.
USD, usd Response
The customer already had this card saved: its saved payment method, with a next_action when the cardholder's bank authenticates the card before its new details are saved
payment_method "pm_test_9kQ2mL7Hs1pXv4cR8tWzAbCdEf"
card, us_bank_account, acss_debit "card"
saved when the session named a customer: the instrument is vaulted and stays on their file. one_time otherwise: chargeable once, before expires_at.
one_time, saved "saved"
active can be charged. consumed: a one-time method already charged. expired: a one-time method past expires_at. detached: removed from the customer's file. requires_action while a card being saved waits on the cardholder's bank (3-D Secure), as next_action says; it then turns active, or failed when nothing was saved (see failure). A method only reads requires_action when its create sent return_url or use_payra_js. A saved method stays active, and chargeable with the details it has, while new details for its card wait on the bank.
active, consumed, expired, detached, requires_action, failed "active"
null
The session the card or account was collected in; for bank details your server sent, the session Payra made for them.
"pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd"
Set when type is card.
Show child attributes
Show child attributes
Set when type is us_bank_account.
Show child attributes
Show child attributes
null
Set when type is acss_debit.
Show child attributes
Show child attributes
null
Show child attributes
Show child attributes
Set while the cardholder's bank wants to authenticate the card before it is saved: on a method that reads requires_action, and on an active saved method your create answered with 200 for a card collected again with a new expiry, name or postal code, which takes those once the step is done and keeps the ones it has if it is not. redirect, when the create sent return_url: send the cardholder to url, a Payra page; they come back to your return_url with ?payment_method=. three_ds_fingerprint and three_ds_challenge, when it sent use_payra_js: Payra Elements runs the step on your page in handleNextAction. Null otherwise.
Show child attributes
Show child attributes
null
Set when status is failed: why the card was not saved. card_authentication_failed: the bank did not authenticate the cardholder, or they closed or left its step. card_verification_failed: the processor refused the card after the bank authenticated it. processing_error: anything else. message is Payra's own sentence. Collect the card again with a new session to retry.
Show child attributes
Show child attributes
null
false
Set on a one-time method.
null
"2026-09-18T14:00:00.000Z"