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: []