openapi: 3.0.1 info: title: Card Payments description: Card Payments root resource, returns links to available payments actions. version: '7' servers: - url: https://try.access.worldpay.com description: testing (try) - url: https://access.worldpay.com description: live paths: /cardPayments/customerInitiatedTransactions: post: summary: Take a card payment description: Take online card payments using our Card Payments API. operationId: authorize parameters: - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json requestBody: content: application/vnd.worldpay.payments-v7+json: schema: $ref: '#/components/schemas/customerInitiatedTransaction' examples: Card payment authorization: description: Payment authorization for GBP 2.50 value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/plain cardNumber: '4444333322221111' expiryDate: month: 5 year: 2035 channel: ecom Card payment authorization with all optional fields: description: Payment authorization for GBP 2.50 with all optional fields value: transactionReference: transaction-ref merchant: entity: default mcc: '1234' paymentFacilitator: schemeId: '12345' independentSalesOrganizationId: '12345' subMerchant: name: Merchant Plc reference: '12345' address: postalCode: SW1 1AA street: Regent Street city: London countryCode: GB state: CA taxReference: '12345' phoneNumber: '0123456789' email: test@email.com instruction: requestAutoSettlement: enabled: false consumerBillPayment: true debtRepayment: true narrative: line1: trading name line2: order number value: currency: GBP amount: 250 paymentInstrument: type: card/plain cardNumber: '4444333322221111' expiryDate: month: 12 year: 2024 cardHolderName: John Appleseed billingAddress: address1: address line 1 address2: address line 2 address3: address line 3 city: city state: state postalCode: '12345' countryCode: IT cvc: '123' riskProfile: https://try.access.worldpay.com/riskProfile/ channel: ecom Card payment authorization using 3DS2 authentication: description: Payment authorization for GBP 2.50 using 3DS2 authentication value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/plain cardNumber: '4444333322221111' expiryDate: month: 5 year: 2035 channel: ecom authentication: threeDS: version: 2.1.0 eci: '05' authenticationValue: MAAAAAAAAAAAAAAAAAAAAAAAAAA= transactionId: c5b808e7-1de1-4069-a17b-f70d3b3b1645 Card payment with a request to store card details: description: Payment authorization with a request to store card on file value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/plain cardNumber: '4444333322221111' expiryDate: month: 5 year: 2035 cvc: '123' customerAgreement: type: cardOnFile storedCardUsage: first channel: ecom Tokenized card payment authorization: description: Tokenized card payment authorization value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/token href: https://try.access.worldpay.com/tokens channel: ecom Network token payment authorization: description: Network token payment authorization value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/networkToken tokenNumber: '4444333322221111' expiryDate: month: 5 year: 2035 channel: ecom authentication: networkToken: cryptogram: MAAAAB= eci: '05' Checkout payment authorization: description: Checkout authorization for GBP 2.50 value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/checkout tokenHref: https://try.access.worldpay.com/tokens cvcHref: https://try.access.worldpay.com/sessions channel: ecom Apple wallet payment authorization: description: Apple wallet payment authorization for GBP 2.50 value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/wallet+applepay walletToken: token channel: ecom Google wallet payment authorization: description: Google wallet payment authorization for GBP 2.50 value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/wallet+googlepay walletToken: token channel: ecom Decrypted Apple Pay authorization: description: Decrypted Apple Pay authorization for GBP 2.50 value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/networkToken+applepay tokenNumber: '4444333322221111' expiryDate: month: 5 year: 2035 channel: ecom authentication: networkToken: cryptogram: MAAAAAAAAAAAAAAAAAAAAAAAAAB= eci: '05' responses: '201': description: The payment authorization has been successfully created content: application/vnd.worldpay.payments-v6.hal+json: schema: oneOf: - $ref: '#/components/schemas/payments_authorize_201_response' - $ref: '#/components/schemas/payments_authorize_201_refusal' discriminator: mapping: authorized: '#/components/schemas/payments_authorize_201_response' refused: '#/components/schemas/payments_authorize_201_refusal' propertyName: outcome examples: Successful payment authorization: description: Payment authorization for GBP 2.50 with a successful outcome value: outcome: authorized riskFactors: - type: cvc risk: notSupplied - type: avs risk: notChecked detail: address - type: avs risk: notChecked detail: postcode issuer: authorizationCode: '675725' scheme: reference: '000000000000020005060720116005062' paymentInstrument: type: card/plain+masked cardBin: '555555' lastFour: '4444' category: consumer countryCode: GB expiryDate: month: 9 year: 2029 cardBrand: mastercard fundingType: credit issuerName: AN ISSUING BANK LTD paymentAccountReference: Q1HJZ28RKA1EBL470G9XYG90R5D3E _links: cardPayments:cancel: href: >- https://try.access.worldpay.com/payments/authorizations/cancellations/ cardPayments:settle: href: >- https://try.access.worldpay.com/payments/settlements/full/ cardPayments:partialSettle: href: >- https://try.access.worldpay.com/payments/settlements/partials/ cardPayments:events: href: https://try.access.worldpay.com/payments/events/ curies: - name: cardPayments href: >- https://try.access.worldpay.com/rels/cardPayments/{rel} templated: true Refused payment authorization: description: Payment authorization with a refused outcome value: outcome: refused refusalCode: '5' refusalDescription: REFUSED riskFactors: - type: cvc risk: notSupplied - type: avs risk: notChecked detail: address - type: avs risk: notChecked detail: postcode /cardPayments/merchantInitiatedTransactions: post: summary: Take a repeat card payment description: Take online payments using our Card Payments API. operationId: recurring parameters: - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json requestBody: content: application/vnd.worldpay.payments-v7+json: schema: $ref: '#/components/schemas/merchantInitiatedTransaction' examples: Subscriptions - Recurring payment authorization: description: Recurring authorization for subscriptions value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/plain cardNumber: '4444333322221111' expiryDate: month: 5 year: 2035 customerAgreement: type: subscription schemeReference: MCCOLXT1C0104 Installments - Recurring payment authorization: description: Recurring authorization for installments value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/plain cardNumber: '4444333322221111' expiryDate: month: 5 year: 2035 customerAgreement: type: installment installmentType: merchant schemeReference: MCCOLXT1C0104 Unscheduled - Recurring payment authorization: description: Recurring authorization for unscheduled payments value: transactionReference: Memory265-13/08/1876 merchant: entity: default instruction: requestAutoSettlement: enabled: false narrative: line1: MindPalace value: currency: GBP amount: 250 paymentInstrument: type: card/plain cardNumber: '4444333322221111' expiryDate: month: 5 year: 2035 customerAgreement: type: unscheduled schemeReference: MCCOLXT1C0104 responses: '201': description: The payment authorization has been successfully created content: application/vnd.worldpay.payments-v6.hal+json: schema: oneOf: - $ref: '#/components/schemas/payments_authorize_201_response' - $ref: '#/components/schemas/payments_authorize_201_refusal' discriminator: mapping: authorized: '#/components/schemas/payments_authorize_201_response' refused: '#/components/schemas/payments_authorize_201_refusal' propertyName: outcome examples: Successful payment authorization: description: Payment authorization for GBP 2.50 with a successful outcome value: outcome: authorized riskFactors: - type: cvc risk: notSupplied - type: avs risk: notChecked detail: address - type: avs risk: notChecked detail: postcode issuer: authorizationCode: '675725' scheme: reference: '000000000000020005060720116005062' paymentInstrument: type: card/plain+masked cardBin: '555555' lastFour: '4444' category: consumer countryCode: GB expiryDate: month: 9 year: 2029 cardBrand: mastercard fundingType: credit issuerName: AN ISSUING BANK LTD paymentAccountReference: Q1HJZ28RKA1EBL470G9XYG90R5D3E _links: cardPayments:cancel: href: >- https://try.access.worldpay.com/payments/authorizations/cancellations/ cardPayments:settle: href: >- https://try.access.worldpay.com/payments/settlements/full/ cardPayments:partialSettle: href: >- https://try.access.worldpay.com/payments/settlements/partials/ cardPayments:events: href: https://try.access.worldpay.com/payments/events/ curies: - name: cardPayments href: >- https://try.access.worldpay.com/rels/cardPayments/{rel} templated: true Refused payment authorization: description: Payment authorization with a refused outcome value: outcome: refused refusalCode: '5' refusalDescription: REFUSED riskFactors: - type: cvc risk: notSupplied - type: avs risk: notChecked detail: address - type: avs risk: notChecked detail: postcode /payments/settlements/{linkData}: post: tags: - Manage Payments summary: Settle for Full amount description: To receive all the funds from the customer, send us a settle request. operationId: settle parameters: - name: linkData in: path description: Action link that's received in your request required: true schema: type: string - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json responses: '202': description: The payment settlement has been accepted content: application/vnd.worldpay.payments-v7+json: examples: Request to fully settle the authorization: description: Request to fully settle the authorization value: _links: cardPayments:refund: href: /payments/settlements/refunds/full/:linkData cardPayments:partialRefund: href: /payments/settlements/refunds/partials/:linkData cardPayments:events: href: /payments/events/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true /payments/settlements/partials/{linkData}: post: tags: - Manage Payments summary: Settle for Partial amount description: >+ To receive a portion of the funds of a payment, send us a partial settle request. operationId: partialSettlement parameters: - name: linkData in: path description: Action link that's received in your request required: true schema: type: string - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json requestBody: content: application/vnd.worldpay.payments-v7+json: schema: $ref: '#/components/schemas/payments_partialSettle' examples: Request to partially settle the authorization: description: Request to partially settle the authorization value: value: amount: 500 currency: EUR reference: partial-settle-reference responses: '202': description: The partial settlement has been accepted content: application/vnd.worldpay.payments-v7+json: examples: Request to partially settle the authorization: description: Request to partially settle the authorization value: _links: cardPayments:refund: href: /payments/settlements/refunds/full/:linkData cardPayments:partialRefund: href: /payments/settlements/refunds/partials/:linkData cardPayments:partialSettle: href: /payments/settlements/partials/:linkData cardPayments:cancel: href: /payments/authorizations/cancellations/:linkData cardPayments:events: href: /payments/events/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true /payments/settlements/refunds/full/{linkData}: post: tags: - Manage Payments summary: Refund Full amount description: >+ Send a refund request to return the full settled amount to your customer. Note: No request body is needed for this request. operationId: refund parameters: - name: linkData in: path description: Action link that's received in your request required: true schema: type: string - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json responses: '202': description: The refund request has been accepted content: application/vnd.worldpay.payments-v7+json: examples: Request to refund an authorization: description: Request to refund an authorization value: _links: cardPayments:events: href: /payments/events/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true /payments/settlements/refunds/partials/{linkData}: post: tags: - Manage Payments summary: Refund Partial amount description: >+ Send a partial refund request to return a portion of the settled amount to your customer. Send the amount to refund and the authorization currency in the body. operationId: partialRefund parameters: - name: linkData in: path description: Action link that's received in your request required: true schema: type: string - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json requestBody: content: application/vnd.worldpay.payments-v7+json: schema: $ref: '#/components/schemas/payments_partialRefund' examples: Request to perform a partial refund of the settlement: description: Request to perform a partial refund of the settlement value: value: amount: 10 currency: EUR reference: partial-refund-reference responses: '202': description: The partial refund has been accepted content: application/vnd.worldpay.payments-v6.hal+json: examples: Request to partially refund an authorization: description: Request to partially refund an authorization value: _links: cardPayments:events: href: /payments/events/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true /payments/authorizations/cancellations/{linkData}: post: tags: - Manage Payments summary: Cancel Authorization description: >+ If you don’t want to proceed with a payment, you can send a cancel request Note: You can only cancel a payment which is authorized. If the payment is settled, you must create a refund. operationId: cancel parameters: - name: linkData in: path description: Action link that's received in your request required: true schema: type: string - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json responses: '202': description: The cancellation request has been accepted content: application/vnd.worldpay.payments-v7+json: examples: Request to cancel an authorization: description: Request to cancel an authorization value: _links: cardPayments:events: href: /payments/events/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true /payments/sales/reversals/{linkData}: post: tags: - Manage Payments summary: Reversal description: >+ Your reversal request is processed as a cancel or refund request. This depends on the time passed after your sale request was submitted. For US entities the payment is refunded after one day after a successful sale request. Any other payment moves to refunded after 15 minutes. Note: No request body is needed for this request. operationId: reversal parameters: - name: linkData in: path description: Action link that's received in your request required: true schema: type: string - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json responses: '202': description: The reversal request has been accepted content: application/vnd.worldpay.payments-v7+json: examples: Request to reverse the settlement: description: Request to reverse the settlement value: _links: cardPayments:events: href: /payments/events/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true /payments/events/{linkData}: get: tags: - Query a Payment summary: Query payment status description: >+ Send a request to find out the current status of your payment after it has been authorized using the events action link. Note: It can take up to 15 minutes for a payment event to update. operationId: eventQuery parameters: - name: linkData in: path description: Action link that's received in your request required: true schema: type: string - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json responses: '200': description: Retrieve the last event of a payment content: application/vnd.worldpay.payments-v7+json: schema: $ref: '#/components/schemas/payments_events_200_response' examples: Querying a payment event with a transaction reference: description: Querying a payment event with a transaction reference value: lastEvent: Authorized _links: cardPayments:cancel: /payments/authorizations/cancellations/:linkData cardPayments:settle: /payments/settlements/full/:linkData cardPayments:partialSettle: /payments/settlements/partials/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true /payments/events: get: tags: - Query a Payment summary: Query payment status Recovery description: >+ Send a request to find out the current status of your payment after it has been authorized using the events action link. This action is only to be used for recovery purposes. Use this action if your authorization requests timed out. The response determines if your authorization request was successful and your next available actions are returned. operationId: eventRecovery parameters: - in: header name: Content-Type required: true schema: type: string example: application/vnd.worldpay.payments-v7+json - in: header name: Accept required: true schema: type: string example: application/vnd.worldpay.payments-v7+json responses: '200': description: Retrieve the last event of a payment content: application/vnd.worldpay.payments-v7+json: schema: $ref: '#/components/schemas/payments_events_recovery_200_response' examples: Querying a payment event with a transaction reference: description: Querying a payment event with a transaction reference value: lastEvent: Authorized _links: cardPayments:cancel: /payments/authorizations/cancellations/:linkData cardPayments:settle: /payments/settlements/full/:linkData cardPayments:partialSettle: /payments/settlements/partials/:linkData curies: - name: payments href: /rels/payments/{rel} templated: true components: schemas: customerInitiatedTransaction: required: - transactionReference - merchant - instruction - channel type: object properties: transactionReference: type: string description: >- A unique reference generated by you that is used to identify a payment throughout its lifecycle. merchant: required: - entity type: object description: An object that contains information about the merchant. properties: entity: type: string description: >- Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries. mcc: type: string description: >- You can apply a merchant category code `mcc` to an individual request. You can only provide an `mcc` if we have enabled the dynamic mcc feature during boarding. If enabled but not provided, `merchant.mcc` defaults to a configured value. paymentFacilitator: required: - schemeId - subMerchant type: object description: >- An object containing Payment Facilitator information. This information is required for every authorization only if you are a Payment Facilitator. properties: schemeId: type: string independentSalesOrganizationId: type: string subMerchant: required: - reference - name - address type: object properties: name: type: string reference: type: string address: type: object required: - postalCode - street - city - countryCode properties: postalCode: type: string street: type: string city: type: string state: type: string countryCode: type: string phoneNumber: type: string taxReference: type: string email: type: string instruction: required: - value - narrative - paymentInstrument - requestAutoSettlement type: object description: An object that contains all information related to the payment. properties: requestAutoSettlement: type: object description: >- Indicate whether the transaction should be sent for settlement now `true` or later `false` at a time of your choosing. properties: enabled: type: boolean value: required: - amount - currency type: object description: >- An object that contains information about the value of the payment. properties: amount: type: integer description: >- The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. currency: type: string description: The three digit currency code. narrative: required: - line1 type: object description: >- The text that appears on your customer's statement. Used to identify the merchant. properties: line1: type: string description: >- The first line of the narrative which appears on your customer's statement (24 characters max. If character is not supported it is replaced with a space). line2: type: string description: >- Additional details about the payment e.g. order number, telephone number. paymentInstrument: type: object oneOf: - $ref: '#/components/schemas/card_plain' - $ref: '#/components/schemas/card_token' - $ref: '#/components/schemas/card_networkToken' - $ref: '#/components/schemas/card_checkout' - $ref: '#/components/schemas/card_wallet_applepay' - $ref: '#/components/schemas/card_wallet_googlepay' - $ref: '#/components/schemas/card_networkToken_applepay' discriminator: mapping: card/plain: '#/components/schemas/card_plain' card/token: '#/components/schemas/card_token' card/networkToken: '#/components/schemas/card_networkToken' card/checkout: '#/components/schemas/card_checkout' card/wallet+applepay: '#/components/schemas/card_wallet_applepay' card/wallet+googlepay: '#/components/schemas/card_wallet_googlepay' card/networkToken+applepay: '#/components/schemas/card_networkToken_applepay' propertyName: type customerAgreement: type: object description: Contains specific customer agreements for the transaction. required: - type oneOf: - $ref: '#/components/schemas/cit_cardOnFile' - $ref: '#/components/schemas/cit_subscription' - $ref: '#/components/schemas/cit_installment' discriminator: propertyName: type mapping: cardOnFile: '#/components/schemas/cit_cardOnFile' subscription: '#/components/schemas/cit_subscription' installment: '#/components/schemas/cit_installment' consumerBillPayment: type: boolean description: >- Consumer Bill Payment is a flag which identifies a bill payment paid by providers on behalf of consumers. debtRepayment: type: boolean description: >- Debt Repayment Indicator is a flag which identifies a payment as being for the purpose of repaying a debt. fundsTransfer: type: object description: >- Contains details of the funds transfer request, which is a money movement for a reason other than the purchase of goods or services (also known as Account Funding Transaction). required: - type properties: type: description: Specify the type of the funds transfer. enum: - accountToAccount - cash - debitTopUp - disbursement - payrollDisbursement - personToPerson - prePaidTopUp - stagedDigitalWallet - transfer type: string purpose: description: Specify the purpose of the funds transfer. enum: - crowdLending - crypto - education - emergency - familySupport - gift - medical - salary - savings - travel - other type: string recipient: type: object description: An object containing details about the recipient of funds. properties: account: type: object description: An object for the account details of the recipient. oneOf: - $ref: '#/components/schemas/fundsTransfer_bankAccount' - $ref: '#/components/schemas/fundsTransfer_card' - $ref: '#/components/schemas/fundsTransfer_wallet' - $ref: '#/components/schemas/fundsTransfer_email' - $ref: '#/components/schemas/fundsTransfer_phone' - $ref: '#/components/schemas/fundsTransfer_socialNetwork' discriminator: propertyName: type mapping: bankAccount: '#/components/schemas/fundsTransfer_bankAccount' card: '#/components/schemas/fundsTransfer_card' wallet: '#/components/schemas/fundsTransfer_wallet' email: '#/components/schemas/fundsTransfer_email' phone: '#/components/schemas/fundsTransfer_phone' socialNetwork: '#/components/schemas/fundsTransfer_socialNetwork' firstName: type: string description: >- Recipient's first name. Must be supplied if `lastName` or `middleName` are provided. middleName: type: string description: Recipient's middle name. lastName: type: string description: >- Recipient's last name. Must be supplied if `firstName` or `middleName` are provided. address: type: object description: Recipient's address properties: address1: type: string description: Must be supplied if `city` is provided. address2: type: string city: type: string description: Must be supplied if `address1` is provided. postalCode: type: string state: type: string description: 1-3 alphanumeric characters and spaces. countryCode: type: string required: - countryCode dateOfBirth: type: object description: Recipient's date of birth properties: day: type: integer month: type: integer year: type: integer required: - day - month - year phoneNumber: type: string description: Recipient's phone number sender: type: object description: An object containing details about the sender of funds. properties: firstName: type: string description: >- Sender's first name. Must be supplied if `lastName` or `middleName` are provided. middleName: type: string description: Sender's middle name. lastName: type: string description: >- Sender's last name. Must be supplied if `firstName` or `middleName` are provided. address: type: object description: Sender's address properties: address1: type: string description: Must be supplied if `city` is provided. address2: type: string city: type: string description: Must be supplied if `address1` is provided. postalCode: type: string state: type: string description: 1-3 alphanumeric characters and spaces. countryCode: type: string required: - countryCode channel: enum: - ecom - moto type: string description: >- Interaction between the cardholder and the merchant. Supply a value of `ecom` to process an eCommerce authorization. Supply a value of `moto` to process an authorization as a Mail Order or Telephone Order transaction. Note: 3DS `authentication` cannot be supplied for MOTO payments. riskProfile: type: string description: >- Used to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments. authentication: description: >- An object containing 3DS or Network Token authentication of the customer. oneOf: - $ref: '#/components/schemas/3DS' - $ref: '#/components/schemas/networkToken' recipient: type: object description: Additional transaction recipient data. properties: accountReference: type: string description: Partial account number of the recipient. lastName: type: string description: Last name of the recipient address: type: object description: Address of the recipient required: - postalCode properties: postalCode: type: string dateOfBirth: type: object description: Birth date of the recipient required: - day - month - year properties: day: type: integer month: type: integer year: type: integer customer: type: object description: Additional customer data. properties: documentReference: type: string description: >- Required for domestic processing in some Latin American countries. merchantInitiatedTransaction: required: - transactionReference - merchant - instruction type: object properties: transactionReference: type: string description: >- A unique reference generated by you that is used to identify a payment throughout its lifecycle. merchant: required: - entity type: object description: An object that contains information about the merchant. properties: entity: type: string description: >- Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries. mcc: type: string description: >- You can apply a merchant category code `mcc` to an individual request. You can only provide an `mcc` if we have enabled the dynamic mcc feature during boarding. If enabled but not provided, `merchant.mcc` defaults to a configured value. paymentFacilitator: required: - schemeId - subMerchant type: object description: >- An object containing Payment Facilitator information. This information is required for every authorization only if you are a Payment Facilitator. properties: schemeId: type: string independentSalesOrganizationId: type: string subMerchant: required: - reference - name - address type: object properties: name: type: string reference: type: string address: type: object required: - postalCode - street - city - countryCode properties: postalCode: type: string street: type: string city: type: string state: type: string countryCode: type: string phoneNumber: type: string taxReference: type: string email: type: string instruction: required: - value - narrative - paymentInstrument - requestAutoSettlement - customerAgreement type: object description: An object that contains all information related to the payment. properties: requestAutoSettlement: type: object description: >- Indicate whether the transaction should be sent for settlement now `true` or later `false` at a time of your choosing. properties: enabled: type: boolean value: required: - amount - currency type: object description: >- An object that contains information about the value of the payment. properties: amount: type: integer description: >- The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. currency: type: string description: The three digit currency code. narrative: required: - line1 type: object description: >- The text that appears on your customer's statement. Used to identify the merchant. properties: line1: type: string description: >- The first line of the narrative which appears on your customer's statement (24 characters max. If character is not supported it is replaced with a space). line2: type: string description: >- Additional details about the payment e.g. order number, telephone number. paymentInstrument: type: object oneOf: - $ref: '#/components/schemas/card_plain_mit' - $ref: '#/components/schemas/card_token_mit' - $ref: '#/components/schemas/card_networkToken' - $ref: '#/components/schemas/card_networkToken_applepay' discriminator: mapping: card/plain: '#/components/schemas/card_plain_mit' card/token: '#/components/schemas/card_token_mit' card/networkToken: '#/components/schemas/card_networkToken' card/networkToken+applepay: '#/components/schemas/card_networkToken_applepay' propertyName: type customerAgreement: type: object description: Contains specific customer agreements for the transaction. required: - type oneOf: - $ref: '#/components/schemas/mit_subscription' - $ref: '#/components/schemas/mit_installment' - $ref: '#/components/schemas/mit_unscheduled' discriminator: propertyName: type mapping: subscription: '#/components/schemas/mit_subscription' installment: '#/components/schemas/mit_installment' unscheduled: '#/components/schemas/mit_unscheduled' consumerBillPayment: type: boolean description: >- Consumer Bill Payment is a flag which identifies a bill payment paid by providers on behalf of consumers. debtRepayment: type: boolean description: >- Debt Repayment Indicator is a flag which identifies a payment as being for the purpose of repaying a debt. fundsTransfer: type: object description: >- Contains details of the funds transfer request, which is a money movement for a reason other than the purchase of goods or services (also known as Account Funding Transaction). required: - type properties: type: description: Specify the type of the funds transfer. enum: - accountToAccount - cash - debitTopUp - disbursement - payrollDisbursement - personToPerson - prePaidTopUp - stagedDigitalWallet - transfer type: string purpose: description: Specify the purpose of the funds transfer. enum: - crowdLending - crypto - education - emergency - familySupport - gift - medical - salary - savings - travel - other type: string recipient: type: object description: An object containing details about the recipient of funds. properties: account: type: object description: An object for the account details of the recipient. oneOf: - $ref: '#/components/schemas/fundsTransfer_bankAccount' - $ref: '#/components/schemas/fundsTransfer_card' - $ref: '#/components/schemas/fundsTransfer_wallet' - $ref: '#/components/schemas/fundsTransfer_email' - $ref: '#/components/schemas/fundsTransfer_phone' - $ref: '#/components/schemas/fundsTransfer_socialNetwork' discriminator: propertyName: type mapping: bankAccount: '#/components/schemas/fundsTransfer_bankAccount' card: '#/components/schemas/fundsTransfer_card' wallet: '#/components/schemas/fundsTransfer_wallet' email: '#/components/schemas/fundsTransfer_email' phone: '#/components/schemas/fundsTransfer_phone' socialNetwork: '#/components/schemas/fundsTransfer_socialNetwork' firstName: type: string description: >- Recipient's first name. Must be supplied if `lastName` or `middleName` are provided. middleName: type: string description: Recipient's middle name. lastName: type: string description: >- Recipient's last name. Must be supplied if `firstName` or `middleName` are provided. address: type: object description: Recipient's address properties: address1: type: string description: Must be supplied if `city` is provided. address2: type: string city: type: string description: Must be supplied if `address1` is provided. postalCode: type: string state: type: string description: 1-3 alphanumeric characters and spaces. countryCode: type: string required: - countryCode dateOfBirth: type: object description: Recipient's date of birth properties: day: type: integer month: type: integer year: type: integer required: - day - month - year phoneNumber: type: string description: Recipient's phone number sender: type: object description: An object containing details about the sender of funds. properties: firstName: type: string description: >- Sender's first name. Must be supplied if `lastName` or `middleName` are provided. middleName: type: string description: Sender's middle name. lastName: type: string description: >- Sender's last name. Must be supplied if `firstName` or `middleName` are provided. address: type: object description: Sender's address properties: address1: type: string description: Must be supplied if `city` is provided. address2: type: string city: type: string description: Must be supplied if `address1` is provided. postalCode: type: string state: type: string description: 1-3 alphanumeric characters and spaces. countryCode: type: string required: - countryCode recipient: type: object description: Additional transaction recipient data. properties: accountReference: type: string description: Partial account number for the recipient. lastName: type: string description: Last name of the recipient address: type: object description: Address of the recipient required: - postalCode properties: postalCode: type: string dateOfBirth: type: object description: Birth date of the recipient required: - day - month - year properties: day: type: integer month: type: integer year: type: integer customer: type: object description: Additional customer data. properties: documentReference: type: string description: >- Required for domestic processing in some Latin American countries. card_plain: required: - type - cardNumber - expiryDate type: object properties: type: enum: - card/plain type: string description: An identifier for the `paymentInstrument` being used. cardNumber: type: string description: Contains your customer's card number. cardHolderName: type: string description: The cardholder's name as it appears on their card. expiryDate: required: - month - year type: object description: Contains your customer's card expiry date. properties: month: type: integer year: type: integer billingAddress: required: - postalCode - countryCode type: object description: Contains the billing address information. properties: address1: type: string description: First line of the address. Required if `city` is provided. address2: type: string description: Second line of the address. address3: type: string description: Third line of the address. city: type: string description: City. Required if `address1` is provided. postalCode: type: string description: >- Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`). state: type: string description: State/province in max 3 characters. countryCode: type: string description: Must be provided in ISO 3166-1 Alpha-2 format. cvc: type: string description: >- CVC is a unique set of 3 or 4 numbers used to verify the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank. card_token: required: - type - href type: object properties: type: enum: - card/token type: string href: type: string description: An `http` address that contains your link to an Access Token cvc: type: string description: >- CVC is a unique set of 3 or 4 numbers used to verify the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank. card_plain_mit: required: - type - cardNumber - expiryDate type: object properties: type: enum: - card/plain type: string description: An identifier for the `paymentInstrument` being used. cardNumber: type: string description: Contains your customer's card number. cardHolderName: type: string description: The cardholder's name as it appears on their card. expiryDate: required: - month - year type: object description: Contains your customer's card expiry date. properties: month: type: integer year: type: integer billingAddress: required: - postalCode - countryCode type: object description: Contains the billing address information. properties: address1: type: string description: First line of the address. Required if `city` is provided. address2: type: string description: Second line of the address. address3: type: string description: Third line of the address. city: type: string description: City. Required if `address1` is provided. postalCode: type: string description: >- Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`). state: type: string description: State/province in max 3 characters. countryCode: type: string description: Must be provided in ISO 3166-1 Alpha-2 format. card_token_mit: required: - type - href type: object properties: type: enum: - card/token type: string href: type: string description: An `http` address that contains your link to an Access Token card_networkToken: required: - type - tokenNumber - expiryDate type: object properties: type: enum: - card/token type: string tokenNumber: type: string description: The network token number. expiryDate: required: - month - year type: object description: Contains your customer's token expiry date. properties: month: type: integer year: type: integer billingAddress: required: - postalCode - countryCode type: object description: Contains the billing address information. properties: address1: type: string description: First line of the address. Required if `city` is provided. address2: type: string description: Second line of the address. address3: type: string description: Third line of the address. city: type: string description: City. Required if `address1` is provided. postalCode: type: string description: >- Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`). state: type: string description: State/province in max 3 characters. countryCode: type: string description: Must be provided in ISO 3166-1 Alpha-2 format. cardHolderName: type: string description: The cardholder's name as it appears on their card. card_checkout: required: - type - tokenHref type: object properties: type: enum: - card/checkout type: string tokenHref: type: string cvcHref: type: string card_wallet_applepay: required: - type - walletToken type: object properties: type: enum: - card/wallet+applepay type: string walletToken: type: string billingAddress: required: - postalCode - countryCode type: object description: Contains the billing address information. properties: address1: type: string description: First line of the address. Required if `city` is provided. address2: type: string description: Second line of the address. address3: type: string description: Third line of the address. city: type: string description: City. Required if `address1` is provided. postalCode: type: string description: >- Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`). state: type: string description: State/province in max 3 characters. countryCode: type: string description: Must be provided in ISO 3166-1 Alpha-2 format. card_wallet_googlepay: required: - type - walletToken type: object properties: type: enum: - card/wallet+googlepay type: string walletToken: type: string billingAddress: required: - postalCode - countryCode type: object description: Contains the billing address information. properties: address1: type: string description: First line of the address. Required if `city` is provided. address2: type: string description: Second line of the address. address3: type: string description: Third line of the address. city: type: string description: City. Required if `address1` is provided. postalCode: type: string description: >- Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`). state: type: string description: State/province in max 3 characters. countryCode: type: string description: Must be provided in ISO 3166-1 Alpha-2 format. card_networkToken_applepay: required: - type - tokenNumber - expiryDate type: object properties: type: enum: - card/networkToken+applepay type: string tokenNumber: type: string description: The network token number. expiryDate: required: - month - year type: object description: Contains your customer's token expiry date. properties: month: type: integer year: type: integer billingAddress: required: - postalCode - countryCode type: object properties: address1: type: string description: First line of the address. Required if `city` is provided. address2: type: string description: Second line of the address. address3: type: string description: Third line of the address. city: type: string description: City. Required if `address1` is provided. postalCode: type: string description: >- Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`). state: type: string description: State/province in max 3 characters. countryCode: type: string description: Must be provided in ISO 3166-1 Alpha-2 format. cardHolderName: type: string description: The cardholder's name as it appears on their card. 3DS: properties: threeDS: type: object required: - version - eci properties: version: type: string description: The version of 3DS used to process the transaction. eci: type: string description: Electronic Commerce Indicator (ECI). authenticationValue: type: string description: >- Required, if `authentication.eci` value is 01, 02, 05 or 06. A cryptographic value that provides evidence of the outcome of a 3DS verification.. transactionId: type: string description: >- Required, if `authentication.eci` value is 01, 02, 05 or 06. A unique authentication transaction identifier, generated by the issuer. networkToken: properties: networkToken: type: object description: >- Network Token authentication. Only allowed for card/networkToken transactions. required: - cryptogram properties: cryptogram: type: string eci: type: string payments_authorize_201_response: required: - outcome type: object properties: outcome: type: string description: Outcome of the request. exemption: required: - result - reason type: object description: >- An exemption result and reason if a risk profile was included in your authorization request. properties: result: type: string reason: type: string issuer: required: - authorizationCode type: object description: An object containing information returned by the issuer. properties: authorizationCode: type: string paymentInstrument: type: object description: Details of the paymentInstrument used. properties: type: type: string cardBin: type: string lastFour: type: string category: type: string issuerName: type: string fundingType: type: string cardBrand: type: string paymentAccountReference: type: string expiryDate: type: object properties: month: type: integer year: type: integer riskFactors: required: - type - risk type: array items: required: - type - risk type: object properties: type: enum: - avs - cvc - riskProfile type: string risk: enum: - notChecked - notMatched - notSupplied - verificationFailed type: string detail: enum: - address - postcode type: string description: >- Any risk factors which have been identified for the authorization. This section will not appear if no risks are identified. scheme: required: - reference type: object description: An object containing information returned by the scheme. properties: reference: type: string payments_authorize_201_refusal: required: - outcome type: object properties: outcome: type: string description: Outcome of the request. exemption: required: - result - reason type: object description: >- An exemption result and reason if a risk profile was included in your authorization request. properties: result: type: string reason: type: string refusalDescription: type: string description: Additional context on the refusal. refusalCode: type: string description: Response code for the request. riskFactors: required: - type - risk type: array items: required: - type - risk type: object properties: type: enum: - avs - cvc - riskProfile type: string risk: enum: - notChecked - notMatched - notSupplied - verificationFailed type: string detail: enum: - address - postcode type: string description: >- Any risk factors which have been identified for the authorization. This section will not appear if no risks are identified. refusalAdvice: type: object description: Contains suggested next actions for this request properties: code: type: string required: - code updatedPaymentInstrument: type: object description: Contains the updates to the payment instrument used. properties: type: type: string tokenNumber: type: string required: - type - tokenNumber payments_partialSettle: required: - value - reference type: object properties: value: required: - amount - currency type: object description: An object that contains information about the value of the payment. properties: amount: type: integer currency: type: string reference: type: string payments_partialSettle_202_response: type: object payments_partialRefund: required: - value - reference type: object properties: value: required: - amount - currency type: object description: An object that contains information about the value of the payment. properties: amount: type: integer currency: type: string reference: type: string payments_events_200_response: required: - lastEvent type: object properties: lastEvent: type: string payments_events_recovery_200_response: required: - lastEvent type: object properties: lastEvent: type: string cit_subscription: required: - type properties: type: type: string description: The processing arrangement agreed with your customer. storedCardUsage: type: string description: Must be set to `first` to begin a new subscription. enum: - first mit_subscription: required: - type properties: type: type: string description: The processing arrangement agreed with your customer. schemeReference: type: string description: A reference returned by the card scheme. cit_installment: type: object required: - type - installmentType properties: type: type: string description: The processing arrangement agreed with your customer. installmentType: type: string description: Defines the type of installments service enum: - merchant - latinAmerica installmentPlan: type: object description: Required only for `latinAmerica` installment type. required: - numberOfInstallments properties: numberOfInstallments: type: integer description: >- Number of installments that the requested amount should be broken into. storedCardUsage: type: string description: >- Specifies the card on file agreement. Must be set to `first` to begin a new merchant installment (optional for `latinAmerica` installments). enum: - first - subsequent mit_installment: required: - type - installmentType properties: type: type: string description: The processing arrangement agreed with your customer. schemeReference: type: string description: A reference returned by the card scheme. installmentType: type: string description: Defines the type of installments service. enum: - merchant mit_unscheduled: required: - type properties: type: type: string description: The processing arrangement agreed with your customer. schemeReference: type: string description: A reference returned by the card scheme. cit_cardOnFile: required: - type - storedCardUsage properties: type: type: string description: The processing arrangement agreed with your customer. storedCardUsage: type: string description: >- Set to `first` to store a card or `subsequent` to use a previously stored card. enum: - first - subsequent fundsTransfer_bankAccount: type: object properties: type: enum: - bankAccount type: string identifierType: type: string enum: - iban - swift - routingNumber iban: type: string description: >- International Bank Account Number. Required if `identifierType` is `iban` accountNumber: type: string description: >- Recipient's account number. Required if `identifierType` is `routingNumber` or `swift` swiftBic: type: string description: >- SWIFT Bank Identification Code. Required if `identifierType` is `swift`. Must be either 8 or 11 alphanumeric characters. routingNumber: type: string description: >- Routing Transit Number. Required if `identifierType` is `routingNumber`. Must be 9 numeric characters. required: - type - identifierType fundsTransfer_card: type: object properties: type: enum: - card type: string cardNumber: type: string description: Recipient's card number. required: - type - cardNumber fundsTransfer_email: type: object properties: type: enum: - email type: string emailAddress: type: string description: Recipient's email address. required: - type - emailAddress fundsTransfer_phone: type: object properties: type: enum: - phone type: string phoneNumber: type: string description: Recipient's phone number. required: - type - phoneNumber fundsTransfer_wallet: type: object properties: type: enum: - wallet type: string walletReference: type: string description: A reference identifying the destination wallet. required: - type - walletReference fundsTransfer_socialNetwork: type: object properties: type: enum: - socialNetwork type: string socialNetworkReference: type: string description: A reference identifying recipient's social network account. required: - type - socialNetworkReference securitySchemes: BasicAuth: type: http scheme: basic security: - BasicAuth: []