> ## Documentation Index > Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Payment ## OpenAPI ````yaml /openapi.yml post /api/v2/payment openapi: 3.0.3 info: title: Gateway API version: v2 contact: name: Support email: support@paybyrd.com license: name: Copyright © Paybyrd termsOfService: https://paybyrd.com/en/privacy servers: - url: https://gateway.paybyrd.com description: Production security: - authByApiKey: [] paths: /api/v2/payment: post: tags: - Payments summary: Create Payment operationId: api-payments-create requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentRequest' examples: POS example: $ref: '#/components/examples/PaymentRequestPOSExample' Card example: $ref: '#/components/examples/PaymentRequestCardExample' Card Payment with Tokenization example: $ref: '#/components/examples/TokenizeCardPaymentRequestExample' Card Tokenized example: $ref: '#/components/examples/PaymentRequestCardTokenizedExample' Card Tokenized with Confirmation Code example: $ref: >- #/components/examples/PaymentRequestCardTokenizedWithConfirmationCodeExample Multibanco example: $ref: '#/components/examples/PaymentRequestMultibancoExample' MB Way example: $ref: '#/components/examples/PaymentRequestMBWayExample' SEPA example: $ref: '#/components/examples/PaymentRequestSepaExample' PayPal example: $ref: '#/components/examples/PaymentRequestPayPalExample' MulticaixaExpress example: $ref: '#/components/examples/PaymentRequestMulticaixaExpressExample' responses: '201': description: '201' content: application/json: examples: Result: $ref: '#/components/examples/PaymentResponseExample' Result Card Payment With Tokenization example: $ref: '#/components/examples/TokenizeCardPaymentResponseExample' Result Multibanco: $ref: '#/components/examples/MultibancoResponseExample' Result MBWay: $ref: '#/components/examples/MBWayResponseExample' Result Sepa: $ref: '#/components/examples/SepaResponseExample' Result PayPal: $ref: '#/components/examples/PayPalResponseExample' Result MulticaixaExpress: $ref: '#/components/examples/MulticaixaExpressResponseExample' schema: $ref: '#/components/schemas/CreatePaymentResponse' '202': description: '202' content: application/json: examples: Result: $ref: '#/components/examples/AcceptedResponseExample' schema: $ref: '#/components/schemas/AcceptedResponse' deprecated: false components: schemas: CreatePaymentRequest: type: object required: - type - amount - currency - orderRef properties: type: type: string description: Define where the payment is created from enum: - Card - POS - OnlineTransfer acceptTokenization: type: boolean description: >- 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. default: false transactionMode: type: string description: >- "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. enum: - initialUnescheduled - initialRecurring - cardHolderInitiatedUnescheduled - merchantInitiatedUnescheduled - merchantInitiatedRecurring fingerprint: type: string description: >- This field represents the checkout fingerPrint. This field is required for tokenization. amount: type: string description: >- Please use the 'isoAmount' field. This is essential due to our multi-currency support. deprecated: true isoAmount: type: integer description: >- Total amount for this transaction in ISO format, with the following pattern "2500" format: int64 bankIdentifierCode: type: string description: The Bank Swift Code brand: type: string description: The card brand card: $ref: '#/components/schemas/Card' confirmationCode: type: string description: >- The value sent to the shopper by email and sms if the payment flow with token requires a confirmation code example: 123456 currency: type: string description: Valid ISO-4217 alpha code e.g EUR expiresAt: type: string description: >- Expiration datetime for MBWay and Multibanco References payments e.g. '2025-12-30T15:59:59+00:00' (ISO 8601 format) isPreAuth: type: boolean description: >- The value that indicates if the payment is a pre-authorization or not default: false orderRef: type: string description: Yours unique reference for this transaction redirectUrl: type: string description: Url where the shopper will be redirected after the payment is done softDescriptor: type: string description: >- Custom text shown on the cardholder's bank statement for this transaction. Returns 400 Bad Request if the value exceeds 22 characters. maxLength: 22 example: Paybyrd Store Purchase shopperFirstName: type: string description: Shopper's first name shopperIp: type: string description: Shopper's ip address shopperLastName: type: string description: Shopper's last name terminalSerialNumber: type: string description: >- 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: type: string description: >- This field contains the unique identifier that represents the token to be used in the payment. format: guid example: 06d49f0f-b7c8-4240-b7be-3bd0bad1c5da shopper: type: object description: Shopper billing information properties: firstName: type: string description: Shopper's first name example: Peter lastName: type: string description: Shopper's last name example: Parker phoneCountryCode: type: integer description: Shopper's phone country code format: int32 example: 351 phoneNumber: type: string description: Shopper's phone number example: '935556731' billingAddress: type: string description: Shopper's billing address example: Avenida Dom João II 40 billingPostalCode: type: string description: Shopper's billing postal code example: 1990-094 billingCity: type: string description: Shopper's billing city example: Lisboa billingCountry: type: string description: Shopper's billing country in ISO 3166-1 alpha-3 format example: PRT CreatePaymentResponse: type: object required: - transactionId - type - isoAmount - amount - currency - orderRef properties: type: type: string description: This is the same value informed in the field "type" in the request. enum: - Card - POS - OnlineTransfer example: Card isoAmount: type: integer description: >- This is the same value informed in the field "isoAmount" in the request. format: int64 amount: type: string description: Total transaction amount. example: '8.15' bankIdentifierCode: type: string description: The Bank Swift Code brand: type: string description: This is the same value informed in the field "brand" in the request. example: VISA card: $ref: '#/components/schemas/CardResponse' code: $ref: '#/components/schemas/PaybyrdCode' currency: type: string description: >- This is the same value informed in the field "currency" in the request. example: EUR description: $ref: '#/components/schemas/PaybyrdDescription' expiresIn: type: integer description: >- This is the same value informed in the field "expiresIn" in the request. example: 48 nullable: true fingerprint: type: string description: >- This field represents the shopper FingerPrint in the Paybyrd's systems. isPreAuth: type: boolean description: >- This is the same value informed in the field "isPreAuth" in the request. example: true default: false orderRef: type: string description: >- This is the same value informed in the field "orderRef" in the request. example: AMZ1962 redirectUrl: type: string description: >- The redirect URL where the Shopper will be redirected when the payment is successful. example: https://your-shop.com/payment-finished shopperFirstName: type: string description: >- This is the same value informed in the field "shopperFirstName" in the request. example: Peter shopperIp: type: string description: >- This is the same value informed in the field "shopperIp" in the request. example: 82.141.10.5 shopperLastName: type: string description: >- This is the same value informed in the field "shopperLastName" in the request. example: Parker shopper: type: object description: Shopper billing information echoed from the request properties: firstName: type: string example: Peter lastName: type: string example: Parker phoneCountryCode: type: integer format: int32 example: 351 phoneNumber: type: string example: '935556731' billingAddress: type: string example: Avenida Dom João II 40 billingPostalCode: type: string example: 1990-094 billingCity: type: string example: Lisboa billingCountry: type: string example: PRT terminalSerialNumber: type: string description: >- This is the same value informed in the field "terminalSerialNumber" in the request. example: EMULATOR0X040506 transactionId: type: string description: >- This field contains the unique identifier that represents the transaction that is created by the payment. format: guid example: e901d7fa-a41a-4c93-bc53-7a08cd72aff4 action: $ref: '#/components/schemas/Action' expiresAt: type: string description: >- Expiration datetime for MBWay and Multibanco References payments (ISO 8601 format) example: '2025-12-30T15:59:59.000Z' AcceptedResponse: type: object properties: code: type: string description: BYRD010 description: type: string description: Request accepted links: $ref: '#/components/schemas/AcceptedLinkResponse' Card: type: object required: - number - expiration - cvv - holder properties: number: type: string description: The card number example: '5149682323738886' expiration: type: string description: The card expiration date with pattern "MM/YY" example: 03/29 cvv: type: string description: The Card Verification Value example: '929' holder: type: string description: The card holder name example: Peter Parker aav: type: string description: The authentication value returned by the 3DS authentication dsTransactionId: type: string description: >- The transaction id returned by the Directory Server executed on 3DS authentication eci: type: string description: The card ECI code returned by the 3DS authentication xid: type: string description: The card transaction identifier returned by the 3DS authentication verificationMethod: type: string description: >- The card verification method indicates if the 3DS was previously performed. When this value is not provided, Paybyrd will respond with the action URL to initiate the 3D Secure flow. For that case, a second step will be required for the payment creation. For 'ThreeDSecure' it is also necessary to provide the 3DS authentication data (aav, dsTransactionId, eci and threeDsVersion). When 'ThreeDSecureAttempt' is provided, a proof of attempt must also be sent. In case you want Paybyrd to handle all the 3DS flow, you must leave this field empty. For this scenario, we will respond with an Action Url that must be triggered on the client side. This will trigger the 3DS flow automatically. enum: - ThreeDSecure - ThreeDSecureAttempt - None CardResponse: type: object properties: number: type: string description: The masked card number example: 514968******8886 expiration: type: string description: The card expiration date with pattern "MM/YY" example: 03/29 cvv: type: string description: The masked card verification value example: '***' holder: type: string description: The card holder name example: Peter Parker aav: type: string description: The authentication value returned by the 3DS authentication dsTransactionId: type: string description: >- The transaction id returned by the Directory Server executed on 3DS authentication eci: type: string description: The card ECI code returned by the 3DS authentication xid: type: string description: The card transaction identifier returned by the 3DS authentication verificationMethod: type: string description: >- The card verification method indicates if the 3DS was previously performed. enum: - ThreeDSecure - ThreeDSecureAttempt - None scheme: type: string description: >- The card scheme. This field will not be always available in the response. enum: - Undefined - Visa - Master - Amex - JCB - Diners - Discover usage: type: string description: >- The card usage. This field will not be always available in the response. enum: - Undefined - Credit - Debit countryCode: type: string description: >- Three letter country code (ISO 3166). This field will not be always available in the response. example: PRT PaybyrdCode: type: string description: >- Represents the Paybyrd code of the web request. To see more details check in [Return Codes](ref:appendix-return-codes) page. example: BYRD200 enum: - BYRD010 - BYRD200 - BYRD201 - BYRD203 - BYRD205 - BYRD206 - BYRD207 - BYRD208 - BYRD230 - BYRD231 - BYRD240 - BYRD290 - BYRD291 - BYRD292 - BYRD294 - BYRD299 - BYRD401 - BYRD403 - BYRD900 - BYRD901 - BYRD999 PaybyrdDescription: type: string example: Operation successfully completed description: >- Represents a textually the description of the Paybyrd code of the web request. To see more details check in [Return Codes](ref:appendix-return-codes) page enum: - 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 Action: type: object required: - type - url properties: type: type: string description: The type of the action to be taken by the merchant enum: - redirect url: type: string description: The URL to be used in order to finalize the payment example: >- https://gateway.paybyrd.com/v1/ThreeDSecure/InitiatePayment?transactionId=0411c4cf-3d6c-4315-ac5e-98fb1d72f11f AcceptedLinkResponse: type: object properties: href: type: string description: The partial url to get the current process. rel: type: string description: The related entity to the process. type: type: string description: The HTTP method which must be used in the partial url. examples: PaymentRequestPOSExample: description: This is an example to use when to do a POS payment. value: type: POS isoAmount: 700 currency: EUR orderRef: AMZ1962 terminalSerialNumber: EMULATOR30X4X5X0 isPreAuth: false PaymentRequestCardExample: description: This is an example of a Card payment. value: type: Card isoAmount: 815 currency: EUR orderRef: AMZ1962 brand: VISA redirectUrl: https://your-shop.com/payment-finished softDescriptor: Paybyrd Store Purchase card: number: '5386134136087954' expiration: 03/29 cvv: '965' holder: Peter Parker threeDSecure: callbackUrl: https://your-shop.com/callback shopper: firstName: Peter lastName: Parker phoneCountryCode: 351 phoneNumber: '935556731' billingAddress: Avenida Dom João II 40 billingPostalCode: 1990-094 billingCity: Lisboa billingCountry: PRT TokenizeCardPaymentRequestExample: description: This is an example of a tokenized card payment. value: type: Card isoAmount: 815 currency: EUR orderRef: AMZ1962 brand: VISA acceptTokenization: true, transactionMode: initialUnescheduled softDescriptor: Paybyrd Store Purchase card: number: '5386134136087954' expiration: 03/29 cvv: '965' holder: Peter Parker threeDSecure: callbackUrl: https://your-shop.com/callback shopper: firstName: Peter lastName: Parker phoneCountryCode: 351 phoneNumber: '935556731' billingAddress: Avenida Dom João II 40 billingPostalCode: 1990-094 billingCity: Lisboa billingCountry: PRT PaymentRequestCardTokenizedExample: description: This is an example to use when to do a Card Tokenized payment. value: type: Card isoAmount: 815 currency: EUR orderRef: AMZ1962 tokenId: 39824983-4a13-42d4-8e85-e2821e494975 PaymentRequestCardTokenizedWithConfirmationCodeExample: description: >- This is an example to use when to do a Card Tokenized payment with confirmation code required. value: type: Card tokenId: 39824983-4a13-42d4-8e85-e2821e494975 confirmationCode: 123456 PaymentRequestMultibancoExample: description: This is an example to use when to do a Multibanco payment. value: type: OnlineTransfer amount: '10.00' currency: EUR orderRef: AMZ1962 brand: SIBS_MULTIBANCO shopperIp: 82.141.10.5 shopperFirstName: Peter shopperLastName: Parker redirectUrl: https://your-shop.com/payment-finished shopper: firstName: Peter lastName: Parker phoneCountryCode: 351 phoneNumber: '935556731' billingAddress: Avenida Dom João II 40 billingPostalCode: 1990-094 billingCity: Lisboa billingCountry: PRT PaymentRequestMBWayExample: description: This is an example to use when to do a MBWay payment. value: type: OnlineTransfer amount: '10.00' currency: EUR orderRef: AMZ1962 brand: MBWAY phoneCountryCode: 123 phoneNumber: 12341234 PaymentRequestSepaExample: description: This is an example to use when to do a Sepa payment. value: type: OnlineTransfer amount: '10.00' currency: EUR orderRef: AMZ1962 brand: SEPA iban: PT55003506519623339578249 email: customer@paybyrd.com country: PRT PaymentRequestPayPalExample: description: This is an example to use when to do a PayPal payment. value: type: OnlineTransfer amount: '10.00' currency: EUR orderRef: AMZ1962 brand: PAYPAL country: PRT culture: pt-PT PaymentRequestMulticaixaExpressExample: description: This is an example to use when creating a MulticaixaExpress payment. value: type: OnlineTransfer amount: '2.00' currency: EUR phoneNumber: '900003000' brand: MULTICAIXAEXPRESS PaymentResponseExample: value: type: Card isoAmount: 815 amount: '8.15' brand: MASTER card: number: 538613******7954 expiration: 03/29 cvv: '***' holder: Peter Parker currency: EUR code: BYRD207 description: Pending redirect expiresIn: 48 isPreAuth: true orderRef: AMZ1962 redirectUrl: https://your-url.com/payment-finished shopperFirstName: Peter shopperIp: 82.141.10.5 shopperLastName: Parker shopper: firstName: Peter lastName: Parker phoneCountryCode: 351 phoneNumber: '935556731' billingAddress: Avenida Dom João II 40 billingPostalCode: 1990-094 billingCity: Lisboa billingCountry: PRT terminalSerialNumber: EMULATOR0X040506 transactionId: e901d7fa-a41a-4c93-bc53-7a08cd72aff4 action: type: redirect url: https://link-s.paybyrd.com/3ds_om8OCbsVG TokenizeCardPaymentResponseExample: value: type: Card isoAmount: 815 amount: '8.15' brand: MASTER acceptTokenization: true card: number: 538613******7954 expiration: 03/29 cvv: '***' holder: Peter Parker currency: EUR code: BYRD207 description: Pending redirect orderRef: AMZ1962 shopper: firstName: Peter lastName: Parker phoneCountryCode: 351 phoneNumber: '935556731' billingAddress: Avenida Dom João II 40 billingPostalCode: 1990-094 billingCity: Lisboa billingCountry: PRT transactionId: e901d7fa-a41a-4c93-bc53-7a08cd72aff4 action: type: redirect url: https://link-s.paybyrd.com/3ds_om8OCbsVG tokenization: tokenId: 46014632-da42-47fe-9324-38823eef70d1 status: Inactive MultibancoResponseExample: value: multibanco: serviceSupplierId: '11854' paymentReference: '999999935' waitForNotification: '1' redirectOptional: '1' type: OnlineTransfer currency: EUR orderRef: abc123 brand: Sibs_Multibanco redirectUrl: https://your-shop.com/payment-finished code: BYRD207 description: Pending redirect transactionId: 39824983-4a13-42d4-8e85-e2821e494975 isoAmount: 1000 acquirerEntity: '11854' acquirerReference: '999999935' shopper: firstName: Peter lastName: Parker phoneCountryCode: 351 phoneNumber: '935556731' billingAddress: Avenida Dom João II 40 billingPostalCode: 1990-094 billingCity: Lisboa billingCountry: PRT action: type: redirect url: >- https://api-redirect-staging.azurewebsites.net/api/v1/Redirect/39824983-4a13-42d4-8e85-e2821e494975 MBWayResponseExample: value: type: OnlineTransfer currency: EUR orderRef: AMZ1962 brand: MBWAY phoneCountryCode: 123 phoneNumber: 12341234 code: BYRD201 description: Payment being processed. Waiting for shopper status: Processing transactionId: 39824983-4a13-42d4-8e85-e2821e494975 isoAmount: 1000 SepaResponseExample: value: type: OnlineTransfer currency: EUR orderRef: abc123 brand: SEPA redirectUrl: https://your-shop.com/payment-finished code: BYRD207 description: Pending redirect transactionId: 39824983-4a13-42d4-8e85-e2821e494975 isoAmount: 1000 action: type: redirect url: >- https://api-redirect-staging.azurewebsites.net/api/v1/Redirect/39824983-4a13-42d4-8e85-e2821e494975 PayPalResponseExample: value: type: OnlineTransfer currency: EUR orderRef: AMZ1962 brand: PAYPAL redirectUrl: https://your-shop.com/payment-finished code: BYRD207 description: Pending redirect transactionId: 39824983-4a13-42d4-8e85-e2821e494975 isoAmount: 1000 action: type: redirect url: >- https://api-redirect-staging.azurewebsites.net/api/v1/Redirect/39824983-4a13-42d4-8e85-e2821e494975 MulticaixaExpressResponseExample: value: multicaixaExpress: deeplink: >- mcxwallet://purchase?qrref=0002010102122607000322052037425304973254042.005802AO5908ProxyPay6006Luanda61081000-10062430532fe4eeddd078343c391d6d10721233a3207034446304F577 deeplinkRedirect: >- https://api.sandbox.proxypay.co.ao/deeplink/CdEzoyRcbQ6u6X3jv85tedGmYMdRGE7it_vGBYrv1RVqEKr8MDAwMjAxMDEwMjEyMjYwNzAwMDMyMjA1MjAzNzQyNTMwNDk3MzI1NDA0Mi4wMDU4MDJBTzU5MDhQcm94eVBheTYwMDZMdWFuZGE2MTA4MTAwMC0xMDA2MjQzMDUzMmZlNGVlZGRkMDc4MzQzYzM5MWQ2ZDEwNzIxMjMzYTMyMDcwMzQ0NDYzMDRGNTc3 qrCodeUrl: >- https://api.sandbox.proxypay.co.ao/qrcode/CdEzoyRcbQ6u6X3jv85tedGmYMdRGE7it_vGBYrv1RVqEKr8MDAwMjAxMDEwMjEyMjYwNzAwMDMyMjA1MjAzNzQyNTMwNDk3MzI1NDA0Mi4wMDU4MDJBTzU5MDhQcm94eVBheTYwMDZMdWFuZGE2MTA4MTAwMC0xMDA2MjQzMDUzMmZlNGVlZGRkMDc4MzQzYzM5MWQ2ZDEwNzIxMjMzYTMyMDcwMzQ0NDYzMDRGNTc3 expiresAt: '2026-05-22T19:14:04Z' type: OnlineTransfer currency: EUR acquirer: PROXYPAY brand: MULTICAIXAEXPRESS paymentMethod: multicaixaexpress redirectUrl: https://paybyrd.com fingerprint: f8d87e66-c0e0-424f-9557-45f638862ee2 code: BYRD201 description: Payment being processed. Waiting for shopper status: Processing requestId: 91e6420b-5fdc-40d5-91e6-3790f4dd7d0e expiresAt: '2026-05-22T18:59:03.7168121Z' marketId: PT acceptTokenization: false transactionMode: None transactionId: 60bf0773-927a-467a-a747-b117e99bc331 amount: '2.00' isoAmount: 200 AcceptedResponseExample: value: code: BYRD010 description: Request accepted links: href: /api/v2/transactions?requestId=93ce3e62-82b9-4570-8248-45915e794fd0 rel: transactions type: GET securitySchemes: authByApiKey: type: apiKey in: header name: x-api-key ````