--- title: "Create a payment" method: POST path: "/payments" tags: ["Payments"] --- # Create a payment `POST /payments` Request a transfer of funds between accounts at banks or other financial institutions. ## Query parameters - `expand` string[] - `include` string[] ## Request body - PaymentRequest — Represents a request to transfer funds between accounts at banks or other financial institutions. - `amount` integer, required — Amount in a currency to be used for the transaction. In the lowest denomination of the currency of the payment. This means that `1234` in GBP represents `£12.34`. - `billingAddress` Address - `firstName` string — First name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `lastName` string — Last name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `phoneNumber` string — Telephone number of the occupant Please use only numbers, spaces and an optional leading +. - `buildingNumberOrName` string — The building number or name. Providing a building number or name separate from `address1` is recommended as some payment service provider (PSP) APIs have a separate field. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at . Please use only letters, spaces and these symbols: `-'.` - `address1` string — First line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address2` string — Second line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address3` string — Third line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `town` string — Town of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `county` string — County of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `postcode` string — Postcode of the address. Please use at least one and no more than 9 alphanumeric characters (excl. spaces). - `country` string — ISO 3166 Alpha-2 Country code - `browserData` BrowserData — Information about the browser used to collect payment details. This data is required by some Payment Service Providers as part of their 3-D Secure flow. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at . - `acceptHeader` string — Exact content of the HTTP accept headers as sent to the merchant from the cardholders browser. - `colorDepth` string — Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from cardholder browser using the `screen.colorDepth` browser property. - `javaEnabled` boolean — Boolean that represents the ability of the cardholder browser to execute java. Value is returned from the `navigator.javaEnabled` browser property. - `language` string — Value representing the browser language as defined in IETF BCP47. Returned from `navigator.language` browser property. - `screenHeight` integer — Total height of the cardholders screen in pixels. Value is returned from the `screen.height` browser property. - `screenWidth` integer — Total width of the cardholders screen in pixels. Value is returned from the `screen.width` browser property. - `timeZone` integer — Time difference between UTC time and the cardholder browser local time, in minutes. This can be retrieved by running `new Date().getTimezoneOffset();` within the browser. - `userAgent` string — Exact content of the HTTP user-agent header, as sent to the merchant from the cardholders browser. - `channel` 'web' | 'ios' | 'android' | 'WEB' | 'IOS' | 'ANDROID' — The type of channel used by the end user for the payment. E.g. If your user is using an iOS app to checkout then channel would be `ios`. This data is required by some Payment Service Providers as part of their 3-D Secure flow. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at . - `currencyCode` string, required — Currency code of the payment (ISO 4217) - `customerDateOfBirth` string, date — Date of birth of the referenced person. While this field is not required by the BR-DGE API; it is highly recommended as some PSPs recommend the inclusion of this field. If you have any questions about whether you should provide customer date of birth, please raise a ticket with the [BR-DGE Support Centre](https://support.br-dge.io/support/home). - `customerEmail` string — Email address of the customer While this field is not required by the BR-DGE API; it is highly recommended as some PSPs consider this a mandatory field. If you have any questions about whether you should provide customer email address, please raise a ticket with the [BR-DGE Support Centre](https://support.br-dge.io/support/home) - `customerFirstName` string — First name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long) Please use only letters, spaces and these symbols: `-'.` While this field is not required by the BR-DGE API; it is highly recommended as some PSPs consider this a mandatory field. If you have any questions about whether you should provide customer first name, please raise a ticket with the [BR-DGE Support Centre](https://support.br-dge.io/support/home) - `customerId` string — The ID of the customer in your system. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `customerIpAddress` string, ipv4 — IP address of the customer - `customerLastName` string — Last name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long) Please use only letters, spaces and these symbols: -'. - `customerOrderCode` string, required — You may provide your own order code to be used in payments This is separate from the BR-DGE order. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `customerPhoneNumber` string — Telephone number of the customer Please use only numbers, spaces and an optional leading +. - `customerSessionId` string — Session Id of the customer Please use only letters, numbers, spaces and these symbols:'[]()@?!\-/.,_&*:;+= - `deliveryAddress` Address - `firstName` string — First name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `lastName` string — Last name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `phoneNumber` string — Telephone number of the occupant Please use only numbers, spaces and an optional leading +. - `buildingNumberOrName` string — The building number or name. Providing a building number or name separate from `address1` is recommended as some payment service provider (PSP) APIs have a separate field. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at . Please use only letters, spaces and these symbols: `-'.` - `address1` string — First line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address2` string — Second line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address3` string — Third line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `town` string — Town of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `county` string — County of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `postcode` string — Postcode of the address. Please use at least one and no more than 9 alphanumeric characters (excl. spaces). - `country` string — ISO 3166 Alpha-2 Country code - `documentId` string — Required for some payment instruments. Please refer to the payment instrument schema documentation to see if this is required and where to source the data. - `documentType` string — The type of identification document. E.g. passport, national identity card, tax ID, etc. Required for some payment instruments. Please refer to the payment instrument schema documentation to see if this is required and where to source the data. - `intent` 'authorize' | 'capture' — By default payments are captured immediately, but you can you can choose to split the authorization and the capture of the payment. * `authorize` - if you intend to capture separately using `POST /payments/{paymentId}/capture` * `capture` - If you intend to capture immediately - `merchantInitiated` 'unscheduled' | 'recurring' — Payments made via BR-DGE are assumed to be Cardholder Initiated Transactions (CIT) unless flagged as Merchant Initiated (MIT). Merchants commonly initiate MITs without the active participation of the cardholder to: - Perform a transaction as a follow-up to a cardholder-initiated transaction (CIT) - Perform a pre-agreed standing instruction from the cardholder for the provision of goods or services Examples of MITs include: - An unscheduled charge for a service such as e-scooter hire - A recurring payment for a magazine subscription You must enter into an agreement with your customer prior to performing MITs, and must use a BR-DGE Card on File Payment Instrument. - `merchantInitiatedDetails` MerchantInitiatedDetails — If the transaction is the first payment within a series of merchant initiated transactions then `initialPayment` should be set to `true` and `previousPaymentId` should be omitted. The paymentId that is returned can then be used to make subsequent transactions, which are not cardholder initiated. When performing a payment that is a subsequent payment, then `initialPayment` should be set to `false` or ommited, and `previousPaymentId` should be set to the returned `paymentId` of the initial payment. This field should be used in conjunction with the `merchantInitiated` field. - `initialPayment` boolean — `true` If this is the first transaction within a series of MIT transactions (a CIT transaction) - `previousPaymentId` string — When the transaction is a subsequent payment, `previousPaymentId` should be set to the `paymentId` returned in the initial payment. If `initialPayment` is set to `true`, then this field *must* be omitted. - `orderDescription` string, required — Description of what the payment is for Please use only letters, numbers, spaces and these symbols:'[]()@?!\-/.,_&*:;+= - `origin` string — The origin URL of the web page used by the end user for the payment, if the `channel` is `web`. This data is required by some payment service providers (PSPs) as part of their 3-D Secure flow. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at . - `paymentInstrument` union, required - ApplePay — A type of [Payment Instrument]. Apple Pay is a digital Wallet that offers your customers a simple, secure, and private way to pay within your iOS and watchOS apps, and on your websites via Safari. For more information please refer to the BR-DGE [Apple Pay feature guide]. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument [Apple Pay feature guide]: https://docs.br-dge.io/docs/features-apple-pay - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `nonce` string, required — If you are directly integrating with Apple Pay APIs on your client app then please refer to our [Apple Pay REST API guide] for details on how to generate an Apple Pay token for BR-DGE Payments. Alternatively you can use the [BR-DGE Web SDK Apple Pay module] to directly generate Apple Pay tokens for BR-DGE Payments. [Apple Pay REST API guide]: https://docs.br-dge.io/docs/rest-api-apple-pay [BR-DGE Web SDK Apple Pay module]: https://docs.br-dge.io/docs/apple-pay-module - AstroPay — A type of [Payment Instrument]. Please note: `documentId`, `documentType`, `customerFirstName`, and `customerLastName` are also required for AstroPay payments if you are a merchant operating in the Gaming industry in Brazil. In this case 'CPF' is the only accepted document type. If you are unsure whether you need to supply this data, please raise a ticket with support on the BR-DGE Support Portal at . [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `redirectUrl` string, required — URL that your customer's browser will be redirected to after completing the transaction. By using unpredictable single-use URLs you can protect yourself from the possibility of bad actors attempting to make it appear that payments had a different outcome to reality. We also recommend that you confirm the outcome of payments via server-to-server calls to BR-DGE. - `userId` string — The customer's AstroPay User ID. If it's included in the request only that user will be able to complete the payment. The User ID is only assigned after a successful request, where it can then be found when confirming the outcome of the payment via our [Payment Status endpoint] or via BR-DGE callback. [Payment Status endpoint]: https://docs.br-dge.io/reference/getpaymentstatususingget - `productCode` string, required — Merchant's unique identifier for the product being purchased. - `productDescription` string, required — Description of the product being purchased. - Bancontact — A type of [Payment Instrument]. Please note: `currencyCode` must be `EUR` and `billingAddress.country` must be `BE`. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `successUrl` string — A url that is invoked after a successful Bancontact payment. - `errorUrl` string — A url that is invoked after an unsuccessful Bancontact payment. - Bank2BankPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument) provided by Walletdoc. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `returnUrl` string, uri, required — A URL that is invoked after processing a bank2bank payment. - `bankName` 'capitec' | 'absa' — The specific bank to be used for the bank2bank payment. If not specified, the user to will be routed to select the specific bank within the redirect page. - `identifier` object — The details used to locate the user's account. - `type` 'national_id' | 'passport' | 'account' | 'mobile_number', required — The type of payment identifier used to locate the user's account. - `value` string, required — The value that corresponds to the `type`. - BluVoucher — A type of [Payment Instrument] Please note: `currencyCode` must be `ZAR`. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `pin` string, required — The voucher PIN - Card — A type of [Payment Instrument] representing a credit or debit payment card. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `nameOnCard` string — Name on the credit or debit card Please use only letters, numbers, spaces and these symbols: -'. - `pan` string, required — PAN of the credit or debit card. - `expiryDate` string, required — Card expiry date in MM-YY format. - `startDate` string — Start date of the credit or debit card. - `issueNumber` integer — Issue number of the credit or debit card. - `cv2` string — CV2 of the credit or debit card Please use only numbers - `tokenize` boolean — If true, then a Card-on-File will be created. If Vault interoperability is enabled on your BR-DGE Retail Channel, PSP tokens will also be provisioned. - `storedCredentialIndicator` 'FIRST' | 'SUBSEQUENT' — Indicates whether a card has been stored externally to our system, and if it has been used previously. Used for the situation where you have previously used and stored the card outside our system. This will override the value sent to the card networks, (e.g. Visa/Mastercard) on the *first* time the card is used within our systems. If your systems don't ever store card details *this field should be ignored*. When sent to us this affects the first time the tokenized card is used within our systems. In the case of a card that you never want tokenized with us, but is tokenized externally, we will require the correct value on every call. This is related to [Credential on file mandate compliance](https://docs.br-dge.io/docs/vault#credentials-on-file-mandate-compliance). ## Possible Values * FIRST - The card has not been previously used in a transaction, this is used as a hint to the networks that the card will be stored from this point onward. * SUBSEQUENT - The card has been previously used in a transaction on your systems, this lets the networks know that this is a previously stored card. *Usage Notes:* * Not sending a value for this implies that you have not stored the card for reuse within your systems. * If your company never stores cards for reuse then there is no need to ever send a value for this field. * This field is optional but *MUST* be filled when using a previously/externally stored card. - ClickToPay — A type of [Payment Instrument]. Click-to-Pay, also called Unified Click-to-Pay or Unified Checkout, is a multi-network digital wallet solution provided by VISA Acceptance. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `nonce` string, required — Upon calling the Click-to-Pay's `checkout()` method, a JSON Web Token (JWT) is returned. Decoding this provides a secondary `uctpResponse.payload` JWT value. This `payload` should be provided to BR-DGE via the `/v1/payment-instruments/single-use` endpoint, with the resulting BR-DGE single-use token provided to this field. - EasyPayPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument). EasyPay allows customers to make payments using cash. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `customerId` string — Unique ID linking the EasyPay request to a specific customer. - EPayPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument). ePay.bg is EasyPay’s digital platform supporting online transactions. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `customerId` string — Unique ID linking the ePay.bg request to a specific customer. - `successUrl` string — URL the customer is directed to after a successful transaction - `failureUrl` string — URL the customer is directed to after an unsuccessful transaction - GooglePay — A type of [Payment Instrument]. For more information please refer to the [Google Pay Feature] page. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument [Google Pay Feature]: https://docs.br-dge.io/docs/features-google-pay - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `nonce` string, required — ## If you integrate directly with the Google Pay™ API Follow the procedure in the Google Pay documentation to integrate your [web](https://developers.google.com/pay/api/web/guides/setup) or [Android](https://developers.google.com/pay/api/android/guides/setup) application. In the step where you choose a payment tokenization method, choose `Gateway`, then set `comcarde` as your `gateway`. If you have not been provided with a `gatewayMerchantId` parameter, please raise a ticket with support on the BR-DGE Support Portal at . ## If you use a BR-DGE SDK The BR-DGE SDK can optionally be used to automate client side interactions with the Google Pay™ API. The SDK will output a nonce that you can directly use. For more information please refer to the [Google Pay Feature](https://docs.br-dge.io/docs/features-google-pay) page. - Ideal — A type of [Payment Instrument]. Please note: `currencyCode` must be `EUR` and `billingAddress.country` must be `NL`. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `successUrl` string — URL that your customer's browser will be redirected to after they successfully authorize a payment via iDEAL. By using unpredictable single-use URLs you can protect yourself from the possibility of bad actors attempting to make it appear that payments had a different outcome to reality. We also recommend that you confirm the outcome of payments via server-to-server calls to BR-DGE. - `errorUrl` string — A url that is invoked after an unsuccessful iDEAL payment. - NetellerPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument). Please see [Paysafe](https://docs.br-dge.io/docs/paysafe-integration) for more information on this integration. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `defaultUrl` string, uri, required — The default URL that a customer is redirected to after user interaction with Neteller. - `failedUrl` string, uri — A URL that a customer is redirected to if the authorization on Neteller fails. - `cancelledUrl` string, uri — A URL that a customer is redirected to if the Neteller request is cancelled. - OneVoucher — A type of [Payment Instrument] Please note: `currencyCode` must be `ZAR` and `amount` must be `0`. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `pin` string, required — The 16 digit PIN from the Voucher - OttVoucher — A type of [Payment Instrument] Please note: `currencyCode` must be `ZAR`. [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `pin` string, required — The voucher PIN - `mobile` string, required — Telephone number of the occupant Please use only numbers, spaces and an optional leading +. - PayPal — A type of [Payment Instrument] [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `nonce` string, required — Nonce value that represents the details of the PayPal payment. - PaysafecardPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument). Please see [Paysafecard](https://docs.br-dge.io/docs/paysafecard-integration) for more information on this integration. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `successUrl` string, required — A url that a customer is redirected to after successful or failed authorization on Paysafecard. - `errorUrl` string, required — A url that a customer is redirected to after customer cancels the payment on Paysafecard - `countryRestriction` string — ISO 3166-1 alpha-2 two-letter country code used to restrict payments to residents of a particular country. - `kycLevel` 'SIMPLE' | 'FULL' — The Know Your Customer (KYC) level of the customer's myPaysafe account. Depending on the country, myPaysafe accounts are offered with SIMPLE and/or FULL customer identification. - `minAge` integer — Restricts payments to myPaysafe customers only, who are equal to or older than the specified age. Please note, this means that it is required that the customer has a registered myPaysafe account to make the payment. - `submerchantId` string — ID used to classify sub-merchants. Values must be agreed with Paysafecard, non-agreed values will lead to a failed payment. - Pix — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument). Pix is an instant payment system created and managed by the Central Bank of Brazil. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `successUrl` string — A URL that is invoked after a successful Pix payment. By using unpredictable single-use URLs you can protect yourself from the possibility of bad actors attempting to make it appear that payments had a different outcome to reality. We also recommend that you confirm the outcome of payments via server-to-server calls to BR-DGE. - `errorUrl` string — A URL that is invoked after an unsuccessful Pix payment. - ProviderThreeDSecureNonce — A type of [Payment Instrument]. Part of the [3-D Secure Payment Flow]. In the event that you get a 3-D Secure additional action required response to a payment request, you can use the [BR-DGE Web SDK Post Response Module] to handle the action and convert it into a nonce you can use to complete the payment with a `ProviderThreeDSecureNonce` [Payment Instrument]. [BR-DGE Web SDK Post Response Module]: https://docs.br-dge.io/docs/post-response-module [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument [3-D Secure Payment Flow]: https://docs.br-dge.io/docs/payment-flows#3-d-secure-payment-flow - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `paymentId` string, required — Payment ID of the payment - `nonce` string, required — Nonce value that represents the details of the payment along with its 3-D Secure authentication outcome - PspTokenInstrument — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument) created directly with the PSP which can be used to make transactions. This payment instrument cannot be used in any payment flows which contains the card PAN (eg Kount/VISA Instalments) In the event of a BR-DGE outage, a merchant will process transactions directly with a PSP and new Card on File will be tokenized with the PSP but BR-DGE will not know about these tokens. BR-DGE will allow the merchant to process payments with these PSP tokens on the BR-DGE platform before migrating the tokenized instruments into BR-DGE. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `token` string, required — The token that represents a payment instrument. - `psp` string, required — The name of the PSP which the token relates to - `customerId` string — A unique customer ID which is required with some PSPs to create a PSP token. Must be the correct customer ID for the provided PSP token - `cv2` string — CV2 of the credit or debit card the this PSP token relates to - `tokenType` string — Identifies the type of a PSP token where a PSP offers different types of PSP tokens. Currently supports: - customer - [Cybersource Customer Token] - paymentInstrument - [Cybersource Standalone Payment Instrument Token] or [Cybersource Customer Payment Instrument Token] [Cybersource Customer Token]: https://developer.cybersource.com/api-reference-assets/index.html#token-management_customer_create-a-customer [Cybersource Standalone Payment Instrument Token]: https://developer.cybersource.com/api-reference-assets/index.html#token-management_payment-instrument_create-a-payment-instrument [Cybersource Customer Payment Instrument Token]: https://developer.cybersource.com/api-reference-assets/index.html#token-management_customer-payment-instrument_create-a-customer-payment-instrument - RevolutPayPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument) for Revolut Pay, an APM provided by Revolut. If providing the `revolutCustomerId` the `revolutCustomerFullName` and `revolutCustomerEmail` fields will be ignored. If the `revolutCustomerId` is not known, or is a new customer, the `revolutCustomerEmail` and `revolutCustomerFullName` will be used to generate a new Revolut customer ID. If `channel` is not provided, or set to `ios` or `android` then `appReturnUrl` is mandatory. If `channel` is set to `web` then `successUrl`, `failureUrl`, and `cancelUrl` are mandatory. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `appReturnUrl` string, uri — A URL that is invoked after processing a Revolut Pay from within the Revolut app. - `successUrl` string, uri — A URL that is invoked after successfully processing a Revolut Pay payment. The value takes precedence over the `appReturnUrl` when using a web browser. - `failureUrl` string, uri — A URL that is invoked after a Revolut Pay payment failure. The value takes precedence over the `appReturnUrl` when using a web browser. - `cancelUrl` string, uri — A URL that is invoked after cancelling a Revolut Pay payment. The value takes precedence over the `appReturnUrl` when using a web browser. - `revolutCustomerId` string, uuid — Revolut customer ID - `revolutCustomerFullName` string — Revolut customer name - `revolutCustomerEmail` string — Revolut customer e-mail - `revolutPhoneNumber` string — Revolut customer phone number - `revolutFingerprint` string — The fingerprint associated to the authorized order's payment method - Tokenized — For use by BR-DGE SDK - `type` string, required — Discriminator field. Please see the discriminator mapping for the PaymentInstrumentRequest schema. - `customerId` string — Identifier for the merchant's customer who owns the payment instrument to be tokenized. - `token` string, required — The token that represents a payment instrument. - `cv2` string — CV2 of the Tokenized payment instrument. - `updateStoredCredentialIndicator` 'USED' — When provided this updates the indicator of whether a card has been stored externally to our system, and if it has been used previously. Used for the situation where you have registered a card with our system, but used it externally before returning to our system to make a subsequent payment. This will override the value sent to the card networks, (e.g. Visa/Mastercard) on the *first* time the card is used within our systems. If you do not use the card outside of the payment flow in our system before the first payment event, this feature can be ignored, as the standard used functionality will track this. This will effectively update the payment instrument's used status before creating the single use token, as such, if an update is needed it is only required on the first payment request in our system. This is related to [Credential on file mandate compliance]. ## Possible Values * USED - The card has been previously used in a transaction on your systems, this lets the networks know that this is a previously stored card. *Usage Notes:* * Not sending a value for this implies no updates are needed, and so the existing status will be used from our system. * The update value is only needed on the first payment on our system, subsequent calls will just result in extra processing. * This field is optional but *MUST* be filled when a card has been used outside our system before making a first payment inside our system. [Credential on file mandate compliance]: https://docs.br-dge.io/docs/vault#credentials-on-file-mandate-compliance - TrustlyPayment — Trustly is an Open Banking [Payment Instrument]. When using this instrument type for a payment, you must provide a customer ID in the `payment.customerId` field. This field is used within Trustly back office to help merchants keep track of the transaction. For more information, please see our [Trustly User Guide]. [Trustly User Guide]: https://docs.br-dge.io/docs/trustly#/ [Payment Instrument]: https://docs.br-dge.io/docs/introduction#payment-instrument - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `successUrl` string, required — A URL that is invoked after a successful Trustly transaction. By using unpredictable single-use URLs you can protect yourself from the possibility of bad actors attempting to make it appear that the transaction had a different outcome to reality. We also recommend that you confirm the outcome of transaction via server-to-server calls to BR-DGE. - `errorUrl` string, required — A URL that is invoked after an unsuccessful Trustly transaction. - `accountId` string — This is Trustly's bank account identifier, used to enable [Trustly Express flow] transactions. Providing the `accountId` streamlines transactions for returning customers, allowing them to bypass steps and complete transactions faster, which enhances customer loyalty and increases conversion rates. The `accountId` can be obtained from: - Payment Instrument Account Selection BR-DGE callback - `GET /v1/payments` response - `GET /v1/payments/{paymentId}/status` response Note: Ensure the `customerId` matches the customer ID from the previous transaction associated with this `accountId`. [Trustly Express flow]: https://eu.developers.trustly.com/doc/reference/trustly-express-overview - SkrillPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument) for Skrill, which is part of the PaySafe Limited Global Payments Platform. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `returnUrl` string, uri — URL to which the customer is returned once the payment is made. If this field is not filled, the Skrill Quick Checkout page closes automatically at the end of the transaction and the customer is returned to the page on your website from where they were redirected to Skrill. - `pendingUrl` string, uri — A URL that is invoked when a Skrill payment is pending. If not provided, customer will not be re-directed should order go to pending state. - `cancelUrl` string, uri — A URL that is invoked after a cancelled Skrill payment. If not provided, cancel button does not appear for customer. - `paymentMethods` string[] — Payment methods allows specification of which payment methods should be shown to the customer. Depending Skrill account configuration, one or more can be provided. If none are provided, customer is allowed to use any payment method set up with their Skrill account of their choice. - `oneTap` object — Skrill 1-Tap Initialization Data if this Skrill payment is intended to initiate a 1-Tap recurring payment series. Leaving this blank will process a standard, one-time Skrill payment. - `onDemandMaxAmount` integer, required — Maximum amount for subsequent payments that will be debited from the customer’s account. In the lowest denomination of the currency of the payment. - `note` string, required — Text shown to the customer in the payment confirmation email as the reason for the Skrill 1-Tap payment. - SkrillOneTapPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument) used exclusively for subsequent Skrill 1-Tap payments. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `oneTapPaymentId` string, required — BR-DGE paymentId for the order where 1-Tap payment was initially set up. - TrueLayerPayment — A type of [Payment Instrument](https://docs.br-dge.io/docs/introduction#payment-instrument) for the TrueLayer Open Banking solution. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `returnUrl` string, uri, required — URL to which the customer is returned once the payment is made. - `providerId` string — The TrueLayer ID of a bank or other financial institution that TrueLayer can initiate payments through. If not provided, the customer will be prompted to select a provider when re-directed to TrueLayer. - `signupPlus` boolean — Boolean value indicating whether Signup+ flow is requested. If set to true, then TrueLayer will capture the user's data, and this data will be returned when you query a payment or get the status of a payment. - `verifyCustomerName` boolean — Boolean value indicating that name verification of the customer is requested. If set to true, the name will be verified before the payment is settled. If your merchant account with TrueLayer is not enabled for verification, the payment may be rejected. Mutually exclusive with verifyCustomerAge. - `verifyCustomerAge` boolean — Boolean value indicating that age verification of the customer is requested. If set to true, the age will be verified before the payment is settled. If your merchant account with TrueLayer is not enabled for verification, the payment may be rejected. Mutually exclusive with verifyCustomerName. - `bankDetails` union — Bank details of the recipient. Requires either country specific bank account details for domestic payments or IBAN details for international payments. - object - `bankDetailsFormat` string, required — International or ISO 3166 Alpha-2 Country code discriminator field. The options are: - IBAN - GB - `iban` string — Valid ISO 13616 International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). - `swiftBic` string — Unique ISO 9362 Bank Identifier Code for cross-border payments. - `bankName` string — Name of the bank. - object - `bankDetailsFormat` string, required — International or ISO 3166 Alpha-2 Country code discriminator field. The options are: - IBAN - GB - `accountNumber` string — 8 digit bank account number. - `sortCode` string — 6 digit sort code (no spaces or dashes). - `swiftBic` string — Unique ISO 9362 Bank Identifier Code for cross-border payments. - `bankName` string — Name of the bank. - `threeDSecureOptions` ThreeDSecureOptions — Some Payment Service Providers allow you to pass parameters to indicate your preferences relating to 3-D Secure. Note: We cannot guarantee that downstream Payment Service Providers will honour your preferences, but we can ensure that your preferences are passed on whenever possible. - `challengeRequested` boolean — Indicates whether the payment request should result in a 3-D Secure challenge and not experience a frictionless flow, if handled by a payment service provider that supports this feature. - `exemptionRequested` boolean — Indicates whether the payment request should be considered for a 3D Secure exemption, if handled by a payment service provider that supports this feature. DEPRECATED: the 'scaExemption' field should be used instead. - `automaticallyStepUp` boolean — Attempt a payment without 3DSecure, and if 3DSecure is requested from the PSP, automatically re-attempt the payment with 3DSecure. - `threeDSecureRequired` boolean — You can indicate that 3-D Secure processing is preferred, usually initializing a 3-D Secure authentication flow. Note that setting this as true does not guarantee that the payment will end up with successful 3-D Secure authentication. Also, setting this to false does not guarantee that 3-D Secure authentication will not be applied to the payment, as some PSPs may choose to apply their own rules around this regardless need to opt-in to 3-D Secure authentication on a per-payment basis. - `externalThreeDSecure` ExternalThreeDSecure — If you want to use an independent 3-D Secure service to authenticate your payment, then you can do so prior to submitting your payment to BR-DGE. Your client app sends the payment details to your server. Your server submits the payment to your 3-D Secure Authentication Service The 3-D Authentication service will authenticate the payment and return the authentication results back to your server. It will include several fields that can be used by the issuer to confirm the authentication results as part of approving the payment. After authentication, the results can be added to the payment and submitted to BR-DGE for processing. Click here for details on the fields that can be included in the BR-DGE API - `eci` string — The Electronic Commerce Indicator (ECI) indicates the type of card holder authentication used for the transaction. For Secure, Authenticated transaction with XID and CAVV present ECI is set to "05" (Visa & eftpos) or "02" (Mastercard). For Secure, Non-authenticated transaction (XID present, CAVV not present) ECI is set to "06" (Visa & eftpos) or "01" (Mastercard). For Secure, Non-authenticated transaction (XID and CAVV not present) ECI is set to "07" (Visa & eftpos) or "00" (Mastercard). - `cavv` string — The CAVV is the card authentication verification value, provided by the 3D Secure Provider. This is Base64 encoded data. - `xid` string — The XID is the transaction ID from the 3D Secure provider. This is Base64 encoded data. - `par` string — This is the PARes value from 3D Secure - `ver` string — This is the VERes value from 3D Secure - `threeDSecureVersion` string — 3DS version used for authenticating the card. The version may include the major, minor, and build numbers, e.g. 2, 2.1, or 2.1.0 are all accepted values. If omitted, this field will default to a value of 1. - `dsTransactionId` string — Directory Server Transaction ID from the 3D Secure provider. This is commonly a string in UUID format. - `ignoreAvs` boolean — You can tell the payment processors to ignore the result of their Address Verification Service (AVS) and process the Payment regardless. This is false by default. Note this only applies to some payment processors. Speak to your payment processor to find out how you can ignore their AVS otherwise. - `riskInstruments` RiskInstruments — Map of optional risk instrument objects which can be used to pass risk information to PSPs or risk engines - `checkoutRiskJs` CheckoutRiskJs — Risk instrument for Checkout's Risk.js product. Checkout's risk engine will also use the customer's IP address if available which can be provided via Payment.customerIpAddress - `deviceSessionId` string, required — device_session_id token generated in Checkout's Risk.js package - `kount` Kount — Risk instrument for Kount risk engine - `sessionId` string, required — [Session ID] used in Kount's [Device Data Collector] [Session ID]: https://developer.kount.com/hc/en-us/sections/5319287642260-Integration-Guide?article=4411121644820 [Device Data Collector]: https://developer.kount.com/hc/en-us/sections/5319287642260-Integration-Guide?article=4411121101844 - `merchant` Merchant — Risk instrument for Merchant risk engine - `cashierId` string — For use by BR-DGE Cashier to link the transaction to a particular Cashier instance. - `merchantTransactionId` string — Your unique identifier that can be used when a connection issue occurs and you don't receive a paymentId. This is an optional field that can be used when querying `GET v1/payments`, `GET v1/payouts` or `GET v1/payments/{paymentId}/refunds`. We will validate the uniqueness of the merchantTransactionId value per retail channel. If a payment/payout/refund is created with merchantTransactionId `abc`, no other payment/payout/refund can be created with `abc`. The merchantTransactionId is a contract between BR-DGE and a merchant. This field will not be mapped downstream to any PSP. In the event that you provide a merchantTransactionId in the second (or third) leg of a 3DS payment, we will ignore this value and will only use the value provided in the initial request. - `scaExemption` 'LOW_VALUE' | 'TRA' — This field allows you to specify a reason for exempting a transaction from Strong Customer Authentication (SCA). - LOW_VALUE - Low-Value Transaction. Use this value if the transaction amount is below the threshold for SCA exemption. - TRA - Transaction Risk Analysis. Use this value if you believe the transaction has a low risk of fraud based on your own risk assessment. NOTE: Even with a valid exemption reason, the card issuer has the final say in whether to grant the exemption. - `customMetadata` CustomMetadata — Optional custom metadata string fields for the transaction. Up to 25 fields can be included with the following constraints: The field name may not be empty or have leading or trailing whitespace, and can consist of upper and lowercase letters, numbers, space, underscore "_", hyphen "-" and single quote "'". Maximum string length of either field name and field value is 200 chars. ## Response `201` Payment request completed successfully. - PaymentResponse — This returns a list of included relationships. This should only be included on the root of the response. - `code` string — [Response Code](https://docs.br-dge.io/docs/response-codes) signifying the outcome of the request. - `message` string — A description of the outcome of the request. - `id` string — The ID of this request. If you can include these when querying the outcome of individual requests, we can track down the root cause faster. - `relationships` object — A map of a specified relation to the identifiable information for that relation. The key of the map is the requested relation information from the include parameter. - `included` IncludedRelationshipsItem[] — A list of included relationships, where applicable these can be included via the include parameter. This conforms to [JSON:API Compound Documents]. [JSON:API Compound Documents]: https://jsonapi.org/format/1.1/#document-compound-documents - union - IncludedRelationshipsItemPaymentInstrument — An included relationship, will include the lookup information and the attributes related to that inclusion. - `attributes` union — The obfuscated details of a Payment Instrument. Can be one of many different instrument types. - PaymentResponseCard — Reusable details which can be returned on various card payment instrument backed payment instrument types. All details which are returned here are considered obfuscated. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `metadata` CardMetadata — If a card payment instrument is used then BR-DGE may be able to provide metadata about the card **Please note: All text will be UPPERCASE and all fields can be null** - … - `expiryDate` string — Card expiry date in MM-YY format. - `fingerprint` string — A unique token that can be used to detect if two BR-DGE tokens represent the same underlying Payment Instrument. - `fingerprintExtended` string — A fingerprint with card expiry date appended in MMYY format. - PaymentResponseTokenized — Reusable details which can be returned on various card payment instrument backed payment instrument types. All details which are returned here are considered obfuscated. - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `metadata` CardMetadata — If a card payment instrument is used then BR-DGE may be able to provide metadata about the card **Please note: All text will be UPPERCASE and all fields can be null** - … - `expiryDate` string — Card expiry date in MM-YY format. - `fingerprint` string — A unique token that can be used to detect if two BR-DGE tokens represent the same underlying Payment Instrument. - `fingerprintExtended` string — A fingerprint with card expiry date appended in MMYY format. - PaymentResponseApplePay — Decrypted Apple Pay information and card metadata - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `metadata` CardMetadata — If a card payment instrument is used then BR-DGE may be able to provide metadata about the card **Please note: All text will be UPPERCASE and all fields can be null** - … - `expiryDate` string — Card expiry date in MM-YY format. - `fingerprint` string — A unique token that can be used to detect if two BR-DGE tokens represent the same underlying Payment Instrument. - `fingerprintExtended` string — A fingerprint with card expiry date appended in MMYY format. - `decryptedPayload` ApplePayDecryptedPayload — [Apple Pay decrypted payload] excluding sensitive fields, such as cryptogram [Apple Pay decrypted payload]: https://developer.apple.com/documentation/passkit_apple_pay_and_wallet/apple_pay/payment_token_format_reference#3949536 - … - PaymentResponseGooglePay — Decrypted Google Pay information and card metadata - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `metadata` CardMetadata — If a card payment instrument is used then BR-DGE may be able to provide metadata about the card **Please note: All text will be UPPERCASE and all fields can be null** - … - `expiryDate` string — Card expiry date in MM-YY format. - `fingerprint` string — A unique token that can be used to detect if two BR-DGE tokens represent the same underlying Payment Instrument. - `fingerprintExtended` string — A fingerprint with card expiry date appended in MMYY format. - `decryptedPayload` GooglePayDecryptedPayload — [Google Pay decrypted payload] excluding sensitive fields, such as cryptogram [Google Pay decrypted payload]: https://developers.google.com/pay/api/android/guides/resources/payment-data-cryptography#encrypted-message - … - PaymentResponseIssuerResponse — Raw Issuer Details - `type` string, required — Discriminator field. Please see the discriminator mapping for the `PaymentInstrument` schema. - `issuerResponse` IssuerResponse — BR-DGE allows you to directly access the original responses from card issuers for transactions processed through [payment processors] that offer the "Card Issuer Raw Responses" feature. [payment processors]: https://docs.br-dge.io/docs/psp-integrations - … - `id` string, required — The identifier for the specified relation. - `type` string, required — The resource type which is applicable for an entity. - IncludedRelationshipsItemIssuerResponse — An included relationship, will include the lookup information and the attributes related to that inclusion. - `attributes` IssuerResponse — BR-DGE allows you to directly access the original responses from card issuers for transactions processed through [payment processors] that offer the "Card Issuer Raw Responses" feature. [payment processors]: https://docs.br-dge.io/docs/psp-integrations - `issuerPaymentMethod` string — MASTERCARD, VISA, etc - `issuerCardType` string — The payment card type - `merchantAdviceCode` string — Merchant Advice - `type` string — This field is unnecessary and will be removed. DEPRECATED: Do not use, it contains no useful information. - `issuerResponse` object — This field provides duplicate Details from the issuer, already available on the same level. DEPRECATED: Do not use, all the relevant fields are available on the same level as this object. - `issuerPaymentMethod` string — MASTERCARD, VISA, etc DEPRECATED: The same information should be accessed from one level up. - `issuerCardType` string — The payment card type DEPRECATED: The same information should be accessed from one level up. - `merchantAdviceCode` string — Merchant Advice DEPRECATED: The same information should be accessed from one level up. - `id` string, required — The identifier for the specified relation. - `type` string, required — The resource type which is applicable for an entity. - `paymentId` string — The ID of this payment - `amount` integer — Amount in a currency to be used for the transaction. In the lowest denomination of the currency of the payment. This means that `1234` in GBP represents `£12.34`. - `currencyCode` string — Currency code of the payment (ISO 4217) - `threeDSecureAction` object — An object that contains values used to continue a 3-D Secure payment. Note: this field is now deprecated, and the 'action' field should be used instead. - `actionRequired` boolean — Boolean value indicating whether further action should be taken after the response is received - `action` Action — Browser redirect action consistent with [BR-DGE Redirect Payment Flow](https://secure.comcarde.com/docs/#redirect-payment-flow). - `type` string — Discriminator field. Please see the discriminator mapping for the Action schema. - `data` object - `url` string — URL to redirect your customer towards. - `installmentsPlan` InstallmentsPlan — Information about any installments plan was that was linked to the payment request and the outcome of its activation or acceptance. - `code` string — [Response Code](https://docs.br-dge.io/docs/response-codes) signifying the outcome of the request. - `message` string — A description of the outcome of the request. - `provider` string — Full name of the provider of this installments plan. - `operation` string — The type of operation being made: Activation: a new plan has been activated Cancellation: an existing plan has been cancelled - `planActivationId` string — Unique code that identifies the acceptance or activation of the installments plan. This code comes from the installments plan provider, not from BR-DGE. - `token` string — Multi-use token for Card on File, if the request asked for one to be created. - `psp` PspInfo - `name` string, required — Name of Payment Service Provider (PSPs). Please see [PSP Integrations] for a list of possible PSPs. [PSP Integrations]: https://docs.br-dge.io/docs/psp-integrations - `transactionId` string, required — Identifier provided by the PSP this payment was routed to. - `switchAccountId` string — Internal switch account identifier for the PSP account that was used to perform the transaction. This is an internally-assigned identifier, not a value provided by the PSP. Please note: PSP account switching feature is still under development and this field is not present in GET responses and notifications yet. - `pspToken` string — The token created by the PSP for the payment instrument. - `pspCardFingerprint` string — The PSP fingerprint for the payment instrument. - `provisionedUserId` string — PSP-specific user ID that was provisioned by the PSP when processing the payment. - `additionalInfo` union — Any additional information returned from interaction with PSP - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customerFirstName` string — Customer's first name - `customerLastName` string — Customer's last name - `customerDateOfBirth` string, date — Customer's date of birth - `customerIpAddress` string, ipv4 — IP address of the customer - `customerId` string — The ID of the customer in your system. - `paysafecardCustomerId` string — Paysafecard identifier for the customer - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customerPaymentOptionId` string — Identifier for the customer Payment Option - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customerPaymentOptionId` string — Identifier for the customer Payment Option - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customer` TrueLayerCustomer — Contains TrueLayer customer information. - `address` Address - `firstName` string — First name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `lastName` string — Last name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `phoneNumber` string — Telephone number of the occupant Please use only numbers, spaces and an optional leading +. - `buildingNumberOrName` string — The building number or name. Providing a building number or name separate from `address1` is recommended as some payment service provider (PSP) APIs have a separate field. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at . Please use only letters, spaces and these symbols: `-'.` - `address1` string — First line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address2` string — Second line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address3` string — Third line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `town` string — Town of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `county` string — County of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `postcode` string — Postcode of the address. Please use at least one and no more than 9 alphanumeric characters (excl. spaces). - `country` string — ISO 3166 Alpha-2 Country code - `dateOfBirth` string, date — Date of birth of the referenced person. While this field is not required by the BR-DGE API; it is highly recommended as some PSPs recommend the inclusion of this field. If you have any questions about whether you should provide customer date of birth, please raise a ticket with the [BR-DGE Support Centre](https://support.br-dge.io/support/home). - `customerId` string — The ID of the customer in TrueLayer's system - `name` string — Customer's full name - `providerId` string — ID of the bank or other financial institution used in this payment in TrueLayer's system - `paymentSourceId` string — ID of the customer's payment source used to perform the payment in TrueLayer's system - `originalTransactionId` string - `accountNumber` string — 8 digit bank account number. - `sortCode` string — 6 digit sort code (no spaces or dashes). - `iban` string — Valid ISO 13616 International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `fingerprint` string — The fingerprint associated to the authorized order's payment method - `name` string — The name of the revolut customer. - `emailAddress` string — The email address of the revolut customer - `paymentRevTag` string — Unique handle for a Revolut customer. - `revolutCustomerId` string, uuid — The unique identifier for the revolut customer. - `billingAddress` RevolutPayBillingAddress - `street_line_1` string — First line of street address information for Revolut customer. - `street_line_2` string — Second line of street address information for Revolut customer.. - `region` string — The region associated with the address. - `city` string — The region associated with the address. - `country_code` string — 2 letter country code of the country associated with the address. - `postcode` string — The postcode associated with the address. - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `vaultId` string — Vault ID generated by PayPal referring to the customer's stored PayPal wallet. - `paymentSource` PaymentSource — Details of the PayPal account used to complete the payment for the PayPal Order. - `name` string — Full name of customer. - `email` string — Email address of the customer. - `accountId` string — PayPal account ID. - `vaultId` string — Vault ID generated by PayPal referring to the customer's stored PayPal wallet. - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `pin` string — voucher pin - `serialNumber` string — voucher serial number - `rawPspResponses` RawPspResponse[], nullable - `httpStatusCode` integer — The http response code for the given call to the external system - `body` string — The response body of the http request to the external system. This is the raw response with sensitive data redacted. We make no guarantees about the format of this field. It is psp dependant. The majority of these responses are in `application/json` but note for certain types of error response they may be `text/html` or `application/xml` - `pspName` string, required — Name of Payment Service Provider (PSPs). Please see [PSP Integrations] for a list of possible PSPs. [PSP Integrations]: https://docs.br-dge.io/docs/psp-integrations - `headers` object — A key/value map of the http headers from the external system. - `paymentAccountReference` string — The Payment Account Reference (PAR) linked the the payment-instrument, if available. See our [dedicated PAR guide](https://docs.br-dge.io/docs/payment-account-reference) for more info. - `pspId` string — Deprecated. Use `psp` object instead. - `riskAssessments` RiskAssessments — An optional map of risk assessment results received from risk engines. - `kount` KountRiskAssessment — Risk assessment from Kount risk engine. - `score` number, double — The [Omniscore] transaction safety rating received from Kount's risk engine. [Omniscore]: https://support.kount.com/hc/en-us/articles/360045236712-Omniscore-Overview - `decision` 'APPROVED' | 'DECLINED' | 'UNAVAILABLE' | 'REVIEW', required — Kount's risk decision Can be one of: - `APPROVED`: Kount risk engine has approved the transaction. - `DECLINED`: Kount risk engine has declined the transaction. - `UNAVAILABLE`: Kount risk engine was unavailable to give a decision. - `REVIEW`: Kount risk engine has advised that manual review of transaction is required. - `reasonCode` string — The **reasonCode** indicates a [Custom Reason Code] you've configured within your Kount dashboard. This code is returned when a specific individual rule you've created in Kount is triggered. To manage or add new custom reason codes and their associated rules, please use your Kount dashboard. [Custom Reason Code]: https://support.kount.com/hc/en-us/articles/360045746411-Set-Up-Custom-Reason-Codes - `transactionId` string — Transaction identifier provided by Kount. - `tags` string[], nullable — List of tags assigned to the transaction by Kount. - `merchant` MerchantRiskAssessment — Risk assessment from Merchant's own risk engine. Can be used to return results when the merchant has a proprietary risk or validation engine they wish to call during the payment or payout flows. - `decision` 'APPROVED' | 'DECLINED' | 'UNAVAILABLE' | 'HELD', required — Merchant's decision Can be one of: - `APPROVED`: Merchant's risk engine has approved the transaction. - `DECLINED`: Merchant's risk engine has declined the transaction. - `UNAVAILABLE`: Merchant's risk engine was unavailable to give a decision. - `HELD`: Merchant’s risk engine has placed the transaction on hold - `code` string — The response code returned by the engine. - `message` string — Message returned by the engine. - `retryable` boolean — Indicates whether transaction can be amended and retried. - `transactionId` string — Transaction identifier returned by the Merchant risk engine. - `rawResponse` RawResponse — Contains a single http response. - `httpStatusCode` integer — The http response code for the given call to the external system - `body` string — The response body of the http request to the external system. This is the raw response with sensitive data redacted. We make no guarantees about the format of this field. It is psp dependant. The majority of these responses are in `application/json` but note for certain types of error response they may be `text/html` or `application/xml` - `customerOrderCode` string — You may provide your own order code to be used in payments This is separate from the BR-DGE order. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `merchantTransactionId` string — Your unique identifier that can be used when a connection issue occurs and you don't receive a paymentId. This is an optional field that can be used when querying `GET v1/payments`, `GET v1/payouts` or `GET v1/payments/{paymentId}/refunds`. We will validate the uniqueness of the merchantTransactionId value per retail channel. If a payment/payout/refund is created with merchantTransactionId `abc`, no other payment/payout/refund can be created with `abc`. The merchantTransactionId is a contract between BR-DGE and a merchant. This field will not be mapped downstream to any PSP. In the event that you provide a merchantTransactionId in the second (or third) leg of a 3DS payment, we will ignore this value and will only use the value provided in the initial request. - `paymentRails` 'EFTPOS' | 'VISA' | 'MASTERCARD' — Payment rails are the systems and networks that are used to move funds between parties. Card networks can act as payment rails. This field contains payment rails used for current payment. - EFTPOS - Australia's domestic debit card payments network - VISA - Visa international payment network - MASTERCARD - Mastercard international payment network - `avsResult` AvsResult — Information about the AVS (Address Verification Service) result. - `code` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' — The AVS (Address Verification Service) result code. | AVS Code | Meaning | |----------|---------------------------------------------------------------| | A | Postal code matches, street address matches. | | B | Postal code matches, street address not checked. | | C | Postal code matches, street address does not match. | | D | Postal code not checked, street address matches. | | E | Postal code does not match, street address matches. | | F | Postal code not checked, street address not checked. | | G | Postal code not checked, street address does not match. | | H | Postal code does not match, street address not checked. | | I | Both postal code and street address do not match. | | J | Both postal code and street address were not provided. | | K | AVS is unavailable. | | L | Postal code was not provided, street address was not checked. | | M | Postal code was not provided, street address matches. | | N | Postal code was not provided, street address does not match. | | O | Postal code was not checked, street address was not provided. | | P | Postal code matches, street address was not provided. | | Q | Postal code does not match, street address was not provided. | - `message` string — A human readable meaning behind the AVS code specified in the `code` field. - `paymentInstrument` union - PaymentInstrumentCard — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentInstrumentApplePay — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentInstrumentGooglePay — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentInstrumentClickToPay — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentPayPal — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - `account` PaymentInstrumentAccountBase - `accountId` string — The unique account identifier used by the payment instrument provider (Skrill, Paypal etc.) The id is only available after the customer has logged in to their account. Only supported on a subset of payment instruments. - PaymentStatusPaymentInstrumentIdeal — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentBancontact — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentTrustly — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - `account` object — Contains Trustly account information. - `accountId` string, required — Trustly's unique ID for this bank account. - `bank` string — The bank for this account. - `town` string — The town of the account holder. - `name` string — The name of the account holder. - `address` string — The address of the account holder. - `postcode` string — The postcode of the account holder. - `descriptor` string — A text that is safe to show the end user for identifying the account. - `lastDigits` string — The last digits of the bank account number. - `clearingHouse` string — The clearing house of the end user's bank account (i.e. the country where the bank account is held). - `verified` boolean — Whether the bank account has been verified. - PaymentStatusPaymentInstrumentPix — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentInstrumentPspTokenInstrument — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentAstroPayInstrument — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentPaysafecard — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - `account` PaymentInstrumentAccountBase - `accountId` string — The unique account identifier used by the payment instrument provider (Skrill, Paypal etc.) The id is only available after the customer has logged in to their account. Only supported on a subset of payment instruments. - PaymentStatusPaymentInstrumentEasyPay — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentEPay — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentNeteller — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - `account` PaymentInstrumentAccountBase - `accountId` string — The unique account identifier used by the payment instrument provider (Skrill, Paypal etc.) The id is only available after the customer has logged in to their account. Only supported on a subset of payment instruments. - PaymentStatusPaymentInstrumentSkrill — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - `account` PaymentInstrumentAccountBase - `accountId` string — The unique account identifier used by the payment instrument provider (Skrill, Paypal etc.) The id is only available after the customer has logged in to their account. Only supported on a subset of payment instruments. - PaymentStatusPaymentInstrumentRevolutPay — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentTrueLayer — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - `userData` TrueLayerUserData — Contains TrueLayer customer account information. - `title` string — Title of the customer. - `firstName` string — First name of the customer. - `lastName` string — Last name of the customer. - `dateOfBirth` string, date — Date of birth of the referenced person. While this field is not required by the BR-DGE API; it is highly recommended as some PSPs recommend the inclusion of this field. If you have any questions about whether you should provide customer date of birth, please raise a ticket with the [BR-DGE Support Centre](https://support.br-dge.io/support/home). - `address` Address - `firstName` string — First name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `lastName` string — Last name of the occupant. Please use only letters, spaces and these symbols: `-'.` - `phoneNumber` string — Telephone number of the occupant Please use only numbers, spaces and an optional leading +. - `buildingNumberOrName` string — The building number or name. Providing a building number or name separate from `address1` is recommended as some payment service provider (PSP) APIs have a separate field. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at . Please use only letters, spaces and these symbols: `-'.` - `address1` string — First line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address2` string — Second line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `address3` string — Third line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `town` string — Town of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `county` string — County of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `postcode` string — Postcode of the address. Please use at least one and no more than 9 alphanumeric characters (excl. spaces). - `country` string — ISO 3166 Alpha-2 Country code - `accountDetails` TrueLayerAccountDetails — TrueLayer Account Details - `accountNumber` string — 8 digit bank account number. - `sortCode` string — 6 digit sort code (no spaces or dashes). - `iban` string — Valid ISO 13616 International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). - `providerId` string — The TrueLayer ID of a bank or other financial institution. - `paymentSourceId` string — The TrueLayer ID of the customer's payment details. - PaymentStatusPaymentInstrumentOneVoucher — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentBluVoucher — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentBank2Bank — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - PaymentStatusPaymentInstrumentOttVoucher — General fields which are valid for a payment instrument. - `type` string, required — Discriminator Field, defines the type of payment instrument. Valid values can be found on the parent object’s discriminator definition in OpenAPI schema. - `scaDetails` ScaDetails — Contains Strong Customer Authentication (SCA) details about the outcome of any 3DS process the payment went through - `eci` string — The Electronic Commerce Indicator (ECI) value that indicates the 3DS authentication level - `authorizationCode` string — The code provided by the PSP in response to a successfully authorized payment. - `blockingRule` BlockingRule — The routing rule which resulted in the transaction being blocked. - `name` string, required — The name of the rule ## Other responses - `202` — The operation has been accepted for processing and the outcome is not yet known. If an action is in the response, please see [post-response-actions], otherwise please refer to the webhook callbacks that are linked to this operation. [post-response-actions]: https://docs.br-dge.io/docs/rest-api-introduction#post-response-actions - `400` — Bad request - the request was in an invalid format or contained invalid information. If have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at with the `id` from the response so we track down the individual requests on our end. - `401` — Unauthorized request. - `409` — Indicates a request conflict. - `422` — Unprocessable Content - The server understood the content type of the request, and the syntax of the request content was correct, but it was unable to process. This scenario can occur when a payment could not be routed to a PSP, for example if the payment was blocked during routing or no PSP config is set up. It is not a bad request as it has passed gateway validation. - `500` — An internal server error occurred upstream while processing the request. If you have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at with the `id` from the response so we track down the individual requests on our end. - `502` — An error occurred upstream while processing the request, possibly on payment processor. If have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at with the ID from the response so we track down the individual requests on our end. --- [API](https://skmtc.net/br-dge/apis/br-dge-transaction-rest-api.md) · [All operations](https://skmtc.net/br-dge/apis/br-dge-transaction-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/br-dge/br-dge-transaction-rest-api/versions/a9c0feac5523/schema)