Create Payment - Paybyrd

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

Show child attributes

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

Show child attributes

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

Show child attributes

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

Show child attributes

terminalSerialNumber

string

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

Example:

"EMULATOR0X040506"

action

object

Show child attributes

expiresAt

string

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

Example:

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