Skip to main content
POST

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
type
enum<string>
required

Define where the payment is created from

Available options:
Card,
POS,
OnlineTransfer
​
amount
string
required
deprecated

Please use the 'isoAmount' field. This is essential due to our multi-currency support.

​
currency
string
required

Valid ISO-4217 alpha code e.g EUR

​
orderRef
string
required

Yours unique reference for this transaction

​
acceptTokenization
boolean
default:false

The value that indicates if the payment should create a token with the given data. You should also define the "transactionMode" to "initialUnescheduled" or "initialRecurring". Tokenization is only available for cards and mbway at the moment.

​
transactionMode
enum<string>

"transactionMode" is used for tokenization and tokenized payments. The value "initialUnescheduled" tokenizes details for future one-time, unscheduled payments. The value "initialRecurring' tokenizes details for the first in a series of scheduled payments. The value "cardHolderInitiatedUnescheduled" is for subsequent unscheduled payment initiated by the cardholder. The value "merchantInitiatedUnescheduled" is for unscheduled payment initiated by the merchant. The value "merchantInitiatedRecurring" is for subsequent scheduled payment initiated by the merchant.

Available options:
initialUnescheduled,
initialRecurring,
cardHolderInitiatedUnescheduled,
merchantInitiatedUnescheduled,
merchantInitiatedRecurring
​
fingerprint
string

This field represents the checkout fingerPrint. This field is required for tokenization.

​
isoAmount
integer<int64>

Total amount for this transaction in ISO format, with the following pattern "2500"

​
bankIdentifierCode
string

The Bank Swift Code

​
brand
string

The card brand

​
card
object
​
confirmationCode
string

The value sent to the shopper by email and sms if the payment flow with token requires a confirmation code

Example:

123456

​
expiresAt
string

Expiration datetime for MBWay and Multibanco References payments e.g. '2025-12-30T15:59:59+00:00' (ISO 8601 format)

​
isPreAuth
boolean
default:false

The value that indicates if the payment is a pre-authorization or not

​
redirectUrl
string

Url where the shopper will be redirected after the payment is done

​
softDescriptor
string

Custom text shown on the cardholder's bank statement for this transaction. Returns 400 Bad Request if the value exceeds 22 characters.

Maximum string length: 22
Example:

"Paybyrd Store Purchase"

​
shopperFirstName
string

Shopper's first name

​
shopperIp
string

Shopper's ip address

​
shopperLastName
string

Shopper's last name

​
terminalSerialNumber
string

In the POS payment flow, it is necessary to identify which terminal initiated the payment. When this parameter is filled, the POS receives a notification to continue the transaction remotely, this feature is called Remote transaction.

​
tokenId
string<guid>

This field contains the unique identifier that represents the token to be used in the payment.

Example:

"06d49f0f-b7c8-4240-b7be-3bd0bad1c5da"

​
shopper
object

Shopper billing information

Response

201

​
type
enum<string>
required

This is the same value informed in the field "type" in the request.

Available options:
Card,
POS,
OnlineTransfer
Example:

"Card"

​
isoAmount
integer<int64>
required

This is the same value informed in the field "isoAmount" in the request.

​
amount
string
required

Total transaction amount.

Example:

"8.15"

​
currency
string
required

This is the same value informed in the field "currency" in the request.

Example:

"EUR"

​
orderRef
string
required

This is the same value informed in the field "orderRef" in the request.

Example:

"AMZ1962"

​
transactionId
string<guid>
required

This field contains the unique identifier that represents the transaction that is created by the payment.

Example:

"e901d7fa-a41a-4c93-bc53-7a08cd72aff4"

​
bankIdentifierCode
string

The Bank Swift Code

​
brand
string

This is the same value informed in the field "brand" in the request.

Example:

"VISA"

​
card
object
​
code
enum<string>

Represents the Paybyrd code of the web request. To see more details check in Return Codes [blocked] page.

Available options:
BYRD010,
BYRD200,
BYRD201,
BYRD203,
BYRD205,
BYRD206,
BYRD207,
BYRD208,
BYRD230,
BYRD231,
BYRD240,
BYRD290,
BYRD291,
BYRD292,
BYRD294,
BYRD299,
BYRD401,
BYRD403,
BYRD900,
BYRD901,
BYRD999
Example:

"BYRD200"

​
description
enum<string>

Represents a textually the description of the Paybyrd code of the web request. To see more details check in Return Codes [blocked] page

Available options:
Request accepted,
Operation successfully completed,
Payment being processed. Waiting for shopper,
An error occurred while processing the payment. Please query the transaction to confirm its status,
Operation rejected,
Operation blocked by velocity,
Pending redirect,
Payment canceled by the shopper,
Payment already refunded,
The refund amount exceeds the remaining balance of the original payment,
Token is expired,
An error occurred while pre processing the transaction. Please review your request and try again,
An error occurred during while preparing transaction for acquiring. Please review your request and try again,
No payment methods available for this operation. Please contact Paybyrd's support,
Transaction could not be updated. Please review your request and try again,
Operation could not be completed. Please review your request and try again,
Resource access is forbidden,
Resource access unauthorized,
Invalid input,
Resource not found,
Operation failed
Example:

"Operation successfully completed"

​
expiresIn
integer | null

This is the same value informed in the field "expiresIn" in the request.

Example:

48

​
fingerprint
string

This field represents the shopper FingerPrint in the Paybyrd's systems.

​
isPreAuth
boolean
default:false

This is the same value informed in the field "isPreAuth" in the request.

Example:

true

​
redirectUrl
string

The redirect URL where the Shopper will be redirected when the payment is successful.

Example:

"https://your-shop.com/payment-finished"

​
shopperFirstName
string

This is the same value informed in the field "shopperFirstName" in the request.

Example:

"Peter"

​
shopperIp
string

This is the same value informed in the field "shopperIp" in the request.

Example:

"82.141.10.5"

​
shopperLastName
string

This is the same value informed in the field "shopperLastName" in the request.

Example:

"Parker"

​
shopper
object

Shopper billing information echoed from the request

​
terminalSerialNumber
string

This is the same value informed in the field "terminalSerialNumber" in the request.

Example:

"EMULATOR0X040506"

​
action
object
​
expiresAt
string

Expiration datetime for MBWay and Multibanco References payments (ISO 8601 format)

Example:

"2025-12-30T15:59:59.000Z"