---
title: "Create a checkout"
method: POST
path: "/v2/checkout"
tags: ["Checkout"]
---
# Create a checkout
`POST /v2/checkout`
## Request body
- union
- CreateCheckoutRequest
- `entity_id` string, required — Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)
- `currency_code` 'AUD', required — Currency code
- `amount` integer, required — Transaction amount - Transaction with zero amount value will be considered as account verification and by default implicitly capture will be set to false for AV transaction
- `customer` string — ID of a Customer created via the Customer API. A customer object can be created and attached to a Checkout. The customer object can store relevant customer details. Some of these details might be required, depending on the payment method and/or authentication mechanisms (e.g., 3DS) used in the Checkout
- `configurations` PaymentConfigurations, required — Payment method configurations
- `card` union — Card payment configuration
- object — Card payment configuration
- `mode` 'PAYMENT' | '3DS_PAYMENT' | 'CARD_CAPTURE' | '3DS' — - `PAYMENT` - A checkout is created with the intent to perform a card payment. OnlinePay takes care of the full payment process and returns the final transaction response to the merchant, alongside any related details to it. Requires providing payment provider contract details.
- `3DS_PAYMENT` - Same as `PAYMENT` but with performing 3DS verification.
- `CARD_CAPTURE` - A checkout is created with intent to retrieve customers card data. The checkout captures the card data of the shopper, encrypts it and returns it to the Merchant. The Merchant then uses the encrypted card data to perform 3DS and/or payments with it.
The following fields are not required:
* amount
* currency_code
Note: This option only returns an encrypted card in the end of the checkout process, no transaction is performed. You must perform the read checkout to get the encrypted card. - `3DS` - A checkout is created with intent to perform 3DS verification for the cardholder. The checkout captures the card data and performs 3DS verification with it and returns both card data and 3DS results to the Merchant. The merchant then can then use the encrypted card data to perform a payment with it. Requires providing 3DS contract details.
- `card_capture_mode` 'v2' | 'v1' — Method of capturing card data. v2 is used by default as the recommended method. v1 is considered deprecated and is not supported for new integrations.
- `cvv_required` boolean — Indicates whether cvv is required
- `input_overrides` union
- InputOverrides — unresolved $ref
- Model2 — unresolved $ref
- `threed_secure` ThreedSecure, required — Used for 3D-Secure payments
- `account_age_indicator` '01' | '02' | '03' | '04' | '05' — Length of time cardholder has had account.
Possible Values:
* 01 - No account
* 02 - Created during transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `account_create_date` string, date — Date the cardholder opened the account. `Format: YYYYMMDD`
- `account_change_indicator` '01' | '02' | '03' | '04' — Length of time since the last change to the cardholder account. This includes shipping address,
new payment account or new user added. Possible Values:
* 01 - Changed during transaction
* 02 - Less than 30 days
* 03 - 30-60 days
* 04 - More than 60 days
- `account_change_date` string, date — Date the cardholder's account was last changed. This includes changes to the billing or shipping address, new payment accounts or new users added.` Format: YYYYMMDD`
- `account_pwd_change_indicator` '01' | '02' | '03' | '04' | '05' — Length of time since the cardholder changed or reset the password on the account.
Possible Values:
* 01 - No change
* 02 - Changed during transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `account_pwd_change_date` string, date — Date the cardholder last changed or reset password on account. `Format: YYYYMMDD`
- `account_id` string — Additional cardholder account information.
- `account_purchases` integer — Number of purchases with this cardholder account during the previous six months.
- `acs_window_size` '01' | '02' | '03' | '04' | '05' — An override field that a merchant can pass in to set the challenge window size to display to the end
cardholder.The ACS will reply with content that is formatted appropriately to this window size to allow
for the best user experience. The sizes are width x height in pixels of the window displayed in
the cardholder browser window. Possible values:
* 01 - 250x400
* 02 - 390x400
* 03 - 500x600
* 04 - 600x400
* 05 - Full page
- `add_card_attempts` integer — Number of add card attempts in the last 24 hours.
- `address_match` 'Y' | 'N' — Indicates whether cardholder billing and shipping addresses match.
Possible Values:
* Y - Shipping address matches billing address
* N - Shipping address does not match billing address
- `alternate_authentication_method` '01' | '02' | '03' | '04' | '05' | '06' — Mechanism used by the cardholder to authenticate to the 3DS requester.
Possible Values:
* 01 - No authentication occurred (e.g. Guest Checkout)
* 02 - Login to the cardholder account at the Merchant system using Merchant system credentials
* 03 - Login to the cardholder account at the Merchant system using a Federated ID
* 04 - Login to the cardholder account at the Merchant system using Issuer credentials
* 05 - Login to the cardholder account at the Merchant system using third-party authentication
* 06 - Login to the cardholder account at the Merchant system using FIDO Authenticator
- `alternate_authentication_date` string, date — Date and time in UTC of the cardholder authentication. ` Format: YYYYMMDDHHMM`
- `alternate_authentication_data` string — Data that documents and supports a specific authentication
process that was sent in the AlternateAuthenticationMethod field.
- `threeds_contract_id` string, required — The ID of the threeDSContract used.
- `authentication_indicator` '01' | '02' | '03' | '04' | '05' | '06' — Indicates the type of Authentication request. 01 - Payment transaction
02 - Recurring transaction
03 - Installment transaction
04 - Add card
05 - Maintain card
06 - Cardholder verification as part of EMV token ID&V
- `category_code` integer — Merchant category code (MCC)
Note: This value is always taken from 3-D Secure Contract. If 3-D Secure Contract is not configured with MCC, Cardinal will use the default value configured.
- `challenge_indicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '90' — NOTE: This is a 2.0 required field, Cardinal will default to 01 on Merchant Configuration
- can be overridden by the merchant. Possible Values:
* 01 - No preference
* 02 - No challenge requested
* 03 - Challenge requested (3DS Requestor Preference)
* 04 - Challenge requested (Mandate)
* 05 - No challenge requested (transactional risk analysis is already performed)
* 06 - No challenge requested (Data share only)
* 07 - No challenge requested (strong consumer authentication is already performed)
* 08 - No challenge requested (utilise whitelist exemption if no challenge required)
* 09 - Challenge requested (whitelist prompt requested if challenge required)
* 90 - CB specific value
- `delivery_email` string — For electronic delivery, email address to which the merchandise was delivered.
- `delivery_time_frame` '01' | '02' | '03' | '04' — Indicates the delivery timeframe.
Possible Values:
* 01 - Electronic delivery
* 02 - Same day shipping
* 03 - Overnight shipping
* 04 - Two or more day shipping
- `enabled` boolean, required — Whether 3DS should be used.
- `fraud_activity` '01' | '02' — Indicates whether the merchant experienced suspicious activity (including previous fraud) on the account.
Possible Values:
* 01 - No suspicious activity
* 02 - Suspicious activity observed
- `gift_card_amount` integer — The purchase amount total for prepaid gift cards in major units.
Example: $123.45 USD = 12345
- `gift_card_currency_code` string — ISO 4217 currency code for the gift card purchased.
- `gift_card_count` integer — Total count of individual prepaid gift cards purchased.
- `installment` number — Indicates the maximum number of authorizations for installment payments. An integer value greater than 1 indicating the maximum number of permitted authorizations for installment payments. ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `message_category` '01' | '02' — Category of the message for a specific use case.
Possible Values:
* 01 - PA (payment)
* 02 - NPA (non payment)
NOTE: Default is payment (01). Configured on Merchant account, or can be overridden on transaction.
- `payment_use_case` '01' | '02' | '03' | '04' | '05' — Indicates the type of payment.The value from this field will be mapped to the data field on the CB-USECASE extension
Possible Values:
* 01 - Single Payment
* 02 - Fixed Amount and Term Subscription
* 03 - Payment By Instalments
* 04 - Payment By Shipment
* 05 - Other Recurring Payments
NOTE: Required for CB transactions (Required if message_category = 01, or message_category = 02 and authentication_indicator = 02 or 03
- `payment_account_indicator` '01' | '02' | '03' | '04' | '05' — Indicates the length of time that the payment account was enrolled in the merchant account.
Possible Values:
* 01 - No account (guest checkout)
* 02 - During the transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `payment_account_age` string, date — Date the payment account was added to the cardholder account. ` Format: YYYYMMDD`
- `pre_order_indicator` '01' | '02' — Indicates whether cardholder is placing an order with a future availability or release date.
Possible Values:
* 01 - Merchandise available
* 02 - Future availability
- `pre_order_date` string, date — Expected date that a pre-ordered purchase will be available. `Format: YYYYMMDD`
- `prior_authentication_data` string — This field carry data that the ACS can use to verify the authentication process
- `prior_authentication_method` '01' | '02' | '03' | '04' — Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.
* 01 - Frictionless authentication occurred by ACS
* 02 - Cardholder challenge occurred by ACS
* 03 - AVS verified
* 04 - Other issuer methods
- `prior_authentication_time` string, date — Date and time in UTC of the prior cardholder authentication. ` Format: YYYYMMDDHHMM`
- `prior_authentication_ref` string — This data element contains a ACS Transaction ID for a prior authenticated transaction.
For example, the first recurring transaction that was authenticated with the cardholder
- `product_code` 'PHY' | 'CHA' | 'ACF' | 'QCT' | 'PAL' — Merchant product code.
Possible Values:
* PHY - Goods/Service Purchase
* CHA - Check Acceptance
* ACF - Account Funding
* QCT - Quasi-Cash Transaction
* PAL - Prepaid Activation and Load
NOTE: This value defaults to PHY. This field can be used to override that value if applicable.
- `recurring_end` string, date — The date after which no further recurring authorizations should be performed. `Format: YYYYMMDD` ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `recurring_frequency` number — Conditional: Integer value indicating the minimum number of days between recurring authorizations. A frequency of monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months. Example: 6 months = 168 ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `reorder_indicator` '01' | '02' — Indicates whether cardholder is placing an order with a future availability or release date.
Possible Values:
* 01 - Merchandise available
* 02 - Future availability
- `requestor_id` string — This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID.
NOTE: This is a 2.0 value only and if passed will override the Requestor Name value that is,
configured on the Merchant's profile.
- `requestor_name` string — This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID.
NOTE: This is a 2.0 value only and if passed will override the Requestor Name value that is configured
on the Merchant's profile.
- `shipping_address_usage_indicator` '01' | '02' | '03' | '04' — Indicates when the shipping address used for transaction was first used.
Possible Values:
* 01 - This transaction
* 02 - Less than 30 days
* 03 - 30-60 days
* 04 - More than 60 days
- `shipping_address_usage_date` string, date — Date when the shipping address used for this transaction was first used.
`Format: YYYYMMDD`
- `shipping_method_indicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' — Indicates shipping method chosen for the transaction.
Possible Values:
* 01 - Ship to cardholder billing address
* 02 - Ship to another verified address on file with merchant
* 03 - Ship to address that is different than billing address
* 04 - Ship to store (store address should be populated on request)
* 05 - Digital goods
* 06 - Travel and event tickets, not shipped
* 07 - Other
- `shipping_name_indicator` '01' | '02' — Indicates if the cardholder name on the account is identical to the
shipping name used for the transaction. Possible Values:
* 01 - Account and shipping name identical
* 02 - Account and shipping name differ
- `total_items` string — Total items in the shopping cart of the shopper
- `merchant_score` string — Merchant score
- `transaction_count_day` integer — Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
- `transaction_count_year` integer — Number of transactions (successful or abandoned) for this cardholder account within the last year.
- `transaction_mode` 'M' | 'P' | 'R' | 'S' | 'T' — Transaction mode identifier. Identifies the channel the transaction originates from. Available Options:
M - Moto (Mail Order Telephone Order)
P - Mobile Device
R - Retail (Physical Store)
S - Computer Device
T - Tablet Device
- `version` '1.0.2' | '2.1.0' | '2.2.0' — This field contains the 3DS version that can be leveraged to force a transaction down the 1.0 rails.
- `white_list_status` 'Y' | 'N' | 'E' | 'P' | 'R' | 'U' — Enables the communication of trusted beneficiary between the ACS, the DS and the 3DS Requestor.
Possible Values:
* `Y` - 3DS Requestor is trustlisted by cardholder
* `N` - 3DS Requestor is not trustlisted by cardholder
* `E` - Not eligible as determined by issuer
* `P` - Pending confirmation by cardholder
* `R` - Cardholder rejected
* `U` - Trustlist status unknown, unavailable, or does not apply
Note: This field may be returned for 2.1.0 if the MasterCard PSD2 extensions are passed and issuer supports them.
- `white_list_status_source` '01' | '02' | '03' — This data element will be populated by the system setting Whitelist Status.
- `capture_now` boolean — True - transaction will be sent as authCapture and automatically captured.
False - transaction will be sent as auth and only authorized. NOT CAPTURED.
If you don't have any value in the capture_now parameter, at the moment of the call the value will be set as TRUE.
- `shopper_interaction` 'ECOMMERCE' — Used to indicate the channel used by to send they checkout link
* ECOMMERCE
- `account_validation` boolean — Indicates whether the card transaction should be processed as Account Validation request instead. If set to true, the amount provided for the Checkout would be ignored and the transaction be processed with amount: 0
- `authorization_type` string — Card Authorization Type (PRE_AUTH, FINAL_AUTH). When capture now is set to true pre-authorization transactions cannot be done.
- `payment_contract_id` union, required
- string — This parameter can be found in the portal on the Payment Provider Contract attached to your organization or given to you by a OnlinePay employee. It is used to retrieve MID and other merchant configurations necessary for a card payment.
- PaymentContractIdDef — unresolved $ref
- `token_preference` CardTokenPreference — unresolved $ref
- `credit_term` 'DEBIT' | 'STANDARD' | 'PREFERRED' | 'INSTALMENT_CREDIT' | 'INSTALMENT_STANDARD' — Determines the transaction type. Only applicable for ABS Acquirer. Available options:
STANDARD - Sale
PREFERRED - Sale - Preferred Isracard
DEBIT - Sale - Direct Debit
INSTALMENT_STANDARD - Instalment standard
INSTALMENT_CREDIT - Instalment credit
- `instalment` InstalmentConfiguration — The details on the instalment scheme that should be enacted by the issuer. Only applicable for ABS Acquirer.
- `max_number_of_instalments` integer, required — The number of individual parts that the total amount should be paid in
- `down_payment_amount` integer — An integer value for down payment amount
- `stored_credential` StoredCredential — Used for transactions with Stored Credentials
- `stored_credential_type` 'SIGNUP' | 'CHARGE', required — must be one of SIGNUP CHARGE
- `first_payment` boolean — Set to true if this signup request also is the first payment. Most relevant for signup using a minor amount, to indicate if that minor amount is just a signup account verification amount or an actual first payment amount as well. Default on this endpoint is that zero amount is not a payment, but any amount provided is a payment. Use this indicator to explicitly tell the intention.
- `consent_text` string — Optional merchant provided text to display to the shopper as a checkbox, requiring their consent for the given sign up, detailing the terms at which the shopper agrees to be charged in the future. If not provided, there will be no consent checkbox.
- `consent_text_dynamic_values` string[] — Optional merchant provided links to be inserted in consent text as a link for the text in brackets.
- `processing_model_details` ProcessingModelDetails, required
- …
- `reference` string
- `scheme_reference` string
- `additional_business_data` AdditionalBusinessData — Merchant defined additional data fields for ABS Acquirer.
- `addendum1` string — Additional field 1 for processor data.
- `addendum2` string — Additional field 2 for processor data.
- `reuse_token` string — The identifier used to represent the Cardholder data.
- object — Card payment configuration
- `mode` 'PAYMENT' | '3DS_PAYMENT' | 'CARD_CAPTURE' | '3DS' — - `PAYMENT` - A checkout is created with the intent to perform a card payment. OnlinePay takes care of the full payment process and returns the final transaction response to the merchant, alongside any related details to it. Requires providing payment provider contract details.
- `3DS_PAYMENT` - Same as `PAYMENT` but with performing 3DS verification.
- `CARD_CAPTURE` - A checkout is created with intent to retrieve customers card data. The checkout captures the card data of the shopper, encrypts it and returns it to the Merchant. The Merchant then uses the encrypted card data to perform 3DS and/or payments with it.
The following fields are not required:
* amount
* currency_code
Note: This option only returns an encrypted card in the end of the checkout process, no transaction is performed. You must perform the read checkout to get the encrypted card. - `3DS` - A checkout is created with intent to perform 3DS verification for the cardholder. The checkout captures the card data and performs 3DS verification with it and returns both card data and 3DS results to the Merchant. The merchant then can then use the encrypted card data to perform a payment with it. Requires providing 3DS contract details.
- `card_capture_mode` 'v2' | 'v1' — Method of capturing card data. v2 is used by default as the recommended method. v1 is considered deprecated and is not supported for new integrations.
- `cvv_required` boolean — Indicates whether cvv is required
- `input_overrides` union
- InputOverrides — unresolved $ref
- Model2 — unresolved $ref
- `threed_secure` ThreedSecure, required — Used for 3D-Secure payments
- `account_age_indicator` '01' | '02' | '03' | '04' | '05' — Length of time cardholder has had account.
Possible Values:
* 01 - No account
* 02 - Created during transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `account_create_date` string, date — Date the cardholder opened the account. `Format: YYYYMMDD`
- `account_change_indicator` '01' | '02' | '03' | '04' — Length of time since the last change to the cardholder account. This includes shipping address,
new payment account or new user added. Possible Values:
* 01 - Changed during transaction
* 02 - Less than 30 days
* 03 - 30-60 days
* 04 - More than 60 days
- `account_change_date` string, date — Date the cardholder's account was last changed. This includes changes to the billing or shipping address, new payment accounts or new users added.` Format: YYYYMMDD`
- `account_pwd_change_indicator` '01' | '02' | '03' | '04' | '05' — Length of time since the cardholder changed or reset the password on the account.
Possible Values:
* 01 - No change
* 02 - Changed during transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `account_pwd_change_date` string, date — Date the cardholder last changed or reset password on account. `Format: YYYYMMDD`
- `account_id` string — Additional cardholder account information.
- `account_purchases` integer — Number of purchases with this cardholder account during the previous six months.
- `acs_window_size` '01' | '02' | '03' | '04' | '05' — An override field that a merchant can pass in to set the challenge window size to display to the end
cardholder.The ACS will reply with content that is formatted appropriately to this window size to allow
for the best user experience. The sizes are width x height in pixels of the window displayed in
the cardholder browser window. Possible values:
* 01 - 250x400
* 02 - 390x400
* 03 - 500x600
* 04 - 600x400
* 05 - Full page
- `add_card_attempts` integer — Number of add card attempts in the last 24 hours.
- `address_match` 'Y' | 'N' — Indicates whether cardholder billing and shipping addresses match.
Possible Values:
* Y - Shipping address matches billing address
* N - Shipping address does not match billing address
- `alternate_authentication_method` '01' | '02' | '03' | '04' | '05' | '06' — Mechanism used by the cardholder to authenticate to the 3DS requester.
Possible Values:
* 01 - No authentication occurred (e.g. Guest Checkout)
* 02 - Login to the cardholder account at the Merchant system using Merchant system credentials
* 03 - Login to the cardholder account at the Merchant system using a Federated ID
* 04 - Login to the cardholder account at the Merchant system using Issuer credentials
* 05 - Login to the cardholder account at the Merchant system using third-party authentication
* 06 - Login to the cardholder account at the Merchant system using FIDO Authenticator
- `alternate_authentication_date` string, date — Date and time in UTC of the cardholder authentication. ` Format: YYYYMMDDHHMM`
- `alternate_authentication_data` string — Data that documents and supports a specific authentication
process that was sent in the AlternateAuthenticationMethod field.
- `threeds_contract_id` string, required — The ID of the threeDSContract used.
- `authentication_indicator` '01' | '02' | '03' | '04' | '05' | '06' — Indicates the type of Authentication request. 01 - Payment transaction
02 - Recurring transaction
03 - Installment transaction
04 - Add card
05 - Maintain card
06 - Cardholder verification as part of EMV token ID&V
- `category_code` integer — Merchant category code (MCC)
Note: This value is always taken from 3-D Secure Contract. If 3-D Secure Contract is not configured with MCC, Cardinal will use the default value configured.
- `challenge_indicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '90' — NOTE: This is a 2.0 required field, Cardinal will default to 01 on Merchant Configuration
- can be overridden by the merchant. Possible Values:
* 01 - No preference
* 02 - No challenge requested
* 03 - Challenge requested (3DS Requestor Preference)
* 04 - Challenge requested (Mandate)
* 05 - No challenge requested (transactional risk analysis is already performed)
* 06 - No challenge requested (Data share only)
* 07 - No challenge requested (strong consumer authentication is already performed)
* 08 - No challenge requested (utilise whitelist exemption if no challenge required)
* 09 - Challenge requested (whitelist prompt requested if challenge required)
* 90 - CB specific value
- `delivery_email` string — For electronic delivery, email address to which the merchandise was delivered.
- `delivery_time_frame` '01' | '02' | '03' | '04' — Indicates the delivery timeframe.
Possible Values:
* 01 - Electronic delivery
* 02 - Same day shipping
* 03 - Overnight shipping
* 04 - Two or more day shipping
- `enabled` boolean, required — Whether 3DS should be used.
- `fraud_activity` '01' | '02' — Indicates whether the merchant experienced suspicious activity (including previous fraud) on the account.
Possible Values:
* 01 - No suspicious activity
* 02 - Suspicious activity observed
- `gift_card_amount` integer — The purchase amount total for prepaid gift cards in major units.
Example: $123.45 USD = 12345
- `gift_card_currency_code` string — ISO 4217 currency code for the gift card purchased.
- `gift_card_count` integer — Total count of individual prepaid gift cards purchased.
- `installment` number — Indicates the maximum number of authorizations for installment payments. An integer value greater than 1 indicating the maximum number of permitted authorizations for installment payments. ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `message_category` '01' | '02' — Category of the message for a specific use case.
Possible Values:
* 01 - PA (payment)
* 02 - NPA (non payment)
NOTE: Default is payment (01). Configured on Merchant account, or can be overridden on transaction.
- `payment_use_case` '01' | '02' | '03' | '04' | '05' — Indicates the type of payment.The value from this field will be mapped to the data field on the CB-USECASE extension
Possible Values:
* 01 - Single Payment
* 02 - Fixed Amount and Term Subscription
* 03 - Payment By Instalments
* 04 - Payment By Shipment
* 05 - Other Recurring Payments
NOTE: Required for CB transactions (Required if message_category = 01, or message_category = 02 and authentication_indicator = 02 or 03
- `payment_account_indicator` '01' | '02' | '03' | '04' | '05' — Indicates the length of time that the payment account was enrolled in the merchant account.
Possible Values:
* 01 - No account (guest checkout)
* 02 - During the transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `payment_account_age` string, date — Date the payment account was added to the cardholder account. ` Format: YYYYMMDD`
- `pre_order_indicator` '01' | '02' — Indicates whether cardholder is placing an order with a future availability or release date.
Possible Values:
* 01 - Merchandise available
* 02 - Future availability
- `pre_order_date` string, date — Expected date that a pre-ordered purchase will be available. `Format: YYYYMMDD`
- `prior_authentication_data` string — This field carry data that the ACS can use to verify the authentication process
- `prior_authentication_method` '01' | '02' | '03' | '04' — Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.
* 01 - Frictionless authentication occurred by ACS
* 02 - Cardholder challenge occurred by ACS
* 03 - AVS verified
* 04 - Other issuer methods
- `prior_authentication_time` string, date — Date and time in UTC of the prior cardholder authentication. ` Format: YYYYMMDDHHMM`
- `prior_authentication_ref` string — This data element contains a ACS Transaction ID for a prior authenticated transaction.
For example, the first recurring transaction that was authenticated with the cardholder
- `product_code` 'PHY' | 'CHA' | 'ACF' | 'QCT' | 'PAL' — Merchant product code.
Possible Values:
* PHY - Goods/Service Purchase
* CHA - Check Acceptance
* ACF - Account Funding
* QCT - Quasi-Cash Transaction
* PAL - Prepaid Activation and Load
NOTE: This value defaults to PHY. This field can be used to override that value if applicable.
- `recurring_end` string, date — The date after which no further recurring authorizations should be performed. `Format: YYYYMMDD` ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `recurring_frequency` number — Conditional: Integer value indicating the minimum number of days between recurring authorizations. A frequency of monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months. Example: 6 months = 168 ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `reorder_indicator` '01' | '02' — Indicates whether cardholder is placing an order with a future availability or release date.
Possible Values:
* 01 - Merchandise available
* 02 - Future availability
- `requestor_id` string — This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID.
NOTE: This is a 2.0 value only and if passed will override the Requestor Name value that is,
configured on the Merchant's profile.
- `requestor_name` string — This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID.
NOTE: This is a 2.0 value only and if passed will override the Requestor Name value that is configured
on the Merchant's profile.
- `shipping_address_usage_indicator` '01' | '02' | '03' | '04' — Indicates when the shipping address used for transaction was first used.
Possible Values:
* 01 - This transaction
* 02 - Less than 30 days
* 03 - 30-60 days
* 04 - More than 60 days
- `shipping_address_usage_date` string, date — Date when the shipping address used for this transaction was first used.
`Format: YYYYMMDD`
- `shipping_method_indicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' — Indicates shipping method chosen for the transaction.
Possible Values:
* 01 - Ship to cardholder billing address
* 02 - Ship to another verified address on file with merchant
* 03 - Ship to address that is different than billing address
* 04 - Ship to store (store address should be populated on request)
* 05 - Digital goods
* 06 - Travel and event tickets, not shipped
* 07 - Other
- `shipping_name_indicator` '01' | '02' — Indicates if the cardholder name on the account is identical to the
shipping name used for the transaction. Possible Values:
* 01 - Account and shipping name identical
* 02 - Account and shipping name differ
- `total_items` string — Total items in the shopping cart of the shopper
- `merchant_score` string — Merchant score
- `transaction_count_day` integer — Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
- `transaction_count_year` integer — Number of transactions (successful or abandoned) for this cardholder account within the last year.
- `transaction_mode` 'M' | 'P' | 'R' | 'S' | 'T' — Transaction mode identifier. Identifies the channel the transaction originates from. Available Options:
M - Moto (Mail Order Telephone Order)
P - Mobile Device
R - Retail (Physical Store)
S - Computer Device
T - Tablet Device
- `version` '1.0.2' | '2.1.0' | '2.2.0' — This field contains the 3DS version that can be leveraged to force a transaction down the 1.0 rails.
- `white_list_status` 'Y' | 'N' | 'E' | 'P' | 'R' | 'U' — Enables the communication of trusted beneficiary between the ACS, the DS and the 3DS Requestor.
Possible Values:
* `Y` - 3DS Requestor is trustlisted by cardholder
* `N` - 3DS Requestor is not trustlisted by cardholder
* `E` - Not eligible as determined by issuer
* `P` - Pending confirmation by cardholder
* `R` - Cardholder rejected
* `U` - Trustlist status unknown, unavailable, or does not apply
Note: This field may be returned for 2.1.0 if the MasterCard PSD2 extensions are passed and issuer supports them.
- `white_list_status_source` '01' | '02' | '03' — This data element will be populated by the system setting Whitelist Status.
- `shopper_interaction` 'ECOMMERCE' | 'MAIL' | 'TELEPHONE' — Used to indicate the channel used by to send they checkout link
* ECOMMERCE
* MAIL - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
* TELEPHONE - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
- object — Card payment configuration
- `mode` 'PAYMENT' | '3DS_PAYMENT' | 'CARD_CAPTURE' | '3DS' — - `PAYMENT` - A checkout is created with the intent to perform a card payment. OnlinePay takes care of the full payment process and returns the final transaction response to the merchant, alongside any related details to it. Requires providing payment provider contract details.
- `3DS_PAYMENT` - Same as `PAYMENT` but with performing 3DS verification.
- `CARD_CAPTURE` - A checkout is created with intent to retrieve customers card data. The checkout captures the card data of the shopper, encrypts it and returns it to the Merchant. The Merchant then uses the encrypted card data to perform 3DS and/or payments with it.
The following fields are not required:
* amount
* currency_code
Note: This option only returns an encrypted card in the end of the checkout process, no transaction is performed. You must perform the read checkout to get the encrypted card. - `3DS` - A checkout is created with intent to perform 3DS verification for the cardholder. The checkout captures the card data and performs 3DS verification with it and returns both card data and 3DS results to the Merchant. The merchant then can then use the encrypted card data to perform a payment with it. Requires providing 3DS contract details.
- `card_capture_mode` 'v2' | 'v1' — Method of capturing card data. v2 is used by default as the recommended method. v1 is considered deprecated and is not supported for new integrations.
- `cvv_required` boolean — Indicates whether cvv is required
- `input_overrides` union
- InputOverrides — unresolved $ref
- Model2 — unresolved $ref
- `capture_now` boolean — True - transaction will be sent as authCapture and automatically captured.
False - transaction will be sent as auth and only authorized. NOT CAPTURED.
If you don't have any value in the capture_now parameter, at the moment of the call the value will be set as TRUE.
- `shopper_interaction` 'ECOMMERCE' | 'MAIL' | 'TELEPHONE' — Used to indicate the channel used by to send they checkout link
* ECOMMERCE
* MAIL - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
* TELEPHONE - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
- `account_validation` boolean — Indicates whether the card transaction should be processed as Account Validation request instead. If set to true, the amount provided for the Checkout would be ignored and the transaction be processed with amount: 0
- `authorization_type` string — Card Authorization Type (PRE_AUTH, FINAL_AUTH). When capture now is set to true pre-authorization transactions cannot be done.
- `payment_contract_id` union, required
- string — This parameter can be found in the portal on the Payment Provider Contract attached to your organization or given to you by a OnlinePay employee. It is used to retrieve MID and other merchant configurations necessary for a card payment.
- PaymentContractIdDef — unresolved $ref
- `token_preference` CardTokenPreference — unresolved $ref
- `credit_term` 'DEBIT' | 'STANDARD' | 'PREFERRED' | 'INSTALMENT_CREDIT' | 'INSTALMENT_STANDARD' — Determines the transaction type. Only applicable for ABS Acquirer.Available options:
STANDARD - Sale
PREFERRED - Sale - Preferred Isracard
DEBIT - Sale - Direct Debit
INSTALMENT_STANDARD - Instalment standard
INSTALMENT_CREDIT - Instalment credit
- `instalment` InstalmentConfiguration — The details on the instalment scheme that should be enacted by the issuer. Only applicable for ABS Acquirer.
- `max_number_of_instalments` integer, required — The number of individual parts that the total amount should be paid in
- `down_payment_amount` integer — An integer value for down payment amount
- `stored_credential` StoredCredential — Used for transactions with Stored Credentials
- `stored_credential_type` 'SIGNUP' | 'CHARGE', required — must be one of SIGNUP CHARGE
- `first_payment` boolean — Set to true if this signup request also is the first payment. Most relevant for signup using a minor amount, to indicate if that minor amount is just a signup account verification amount or an actual first payment amount as well. Default on this endpoint is that zero amount is not a payment, but any amount provided is a payment. Use this indicator to explicitly tell the intention.
- `consent_text` string — Optional merchant provided text to display to the shopper as a checkbox, requiring their consent for the given sign up, detailing the terms at which the shopper agrees to be charged in the future. If not provided, there will be no consent checkbox.
- `consent_text_dynamic_values` string[] — Optional merchant provided links to be inserted in consent text as a link for the text in brackets.
- `processing_model_details` ProcessingModelDetails, required
- …
- `reference` string
- `scheme_reference` string
- `additional_business_data` AdditionalBusinessData — Merchant defined additional data fields for ABS Acquirer.
- `addendum1` string — Additional field 1 for processor data.
- `addendum2` string — Additional field 2 for processor data.
- `reuse_token` string — The identifier used to represent the Cardholder data.
- `fraud_protection_contract` string — Fraud Protection Contract Id
- object — Card payment configuration
- `mode` 'PAYMENT' | '3DS_PAYMENT' | 'CARD_CAPTURE' | '3DS' — - `PAYMENT` - A checkout is created with the intent to perform a card payment. OnlinePay takes care of the full payment process and returns the final transaction response to the merchant, alongside any related details to it. Requires providing payment provider contract details.
- `3DS_PAYMENT` - Same as `PAYMENT` but with performing 3DS verification.
- `CARD_CAPTURE` - A checkout is created with intent to retrieve customers card data. The checkout captures the card data of the shopper, encrypts it and returns it to the Merchant. The Merchant then uses the encrypted card data to perform 3DS and/or payments with it.
The following fields are not required:
* amount
* currency_code
Note: This option only returns an encrypted card in the end of the checkout process, no transaction is performed. You must perform the read checkout to get the encrypted card. - `3DS` - A checkout is created with intent to perform 3DS verification for the cardholder. The checkout captures the card data and performs 3DS verification with it and returns both card data and 3DS results to the Merchant. The merchant then can then use the encrypted card data to perform a payment with it. Requires providing 3DS contract details.
- `card_capture_mode` 'v2' | 'v1' — Method of capturing card data. v2 is used by default as the recommended method. v1 is considered deprecated and is not supported for new integrations.
- `cvv_required` boolean — Indicates whether cvv is required
- `input_overrides` union
- InputOverrides — unresolved $ref
- Model2 — unresolved $ref
- `google_pay` GooglePayPaymentConfig — Google Pay payment configuration
- `capture_now` boolean — True - transaction will be sent as authCapture and automatically captured.
False - transaction will be sent as auth and only authorized. NOT CAPTURED.
If you don't have any value in the capture_now parameter, at the moment of the call the value will be set as TRUE.
- `account_validation` boolean — Indicates whether the card transaction should be processed as Account Validation request instead. If set to true, the amount provided for the Checkout would be ignored and the transaction be processed with amount: 0
- `card` GooglePayCardConfigRequest
- `sca_compliance_level` 'NONE' | 'WALLET' | 'FORCE_3DS', required — Strong Customer Authentication (SCA) compliance level, possible values * NONE: No SCA required. * WALLET: based on the assurance details, if those are false, Google Pay will indicate the PSP to trigger 3DS which in this case will be required. Details [here](https://developers.google.com/pay/api/web/reference/response-objects#assurance-details-specifications) * FORCE_3DS: SCA will be triggered. Regarding the liability shift, please check [this page](https://developers.googleblog.com/en/google-pay-enabling-liability-shift-for-eligible-visa-device-token-transactions-globally/)
- `threed_secure` ThreeDSData, required — Used for 3D-Secure payments
- `account_age_indicator` '01' | '02' | '03' | '04' | '05' — Length of time cardholder has had account.
Possible Values:
* 01 - No account
* 02 - Created during transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `account_create_date` string, date — Date the cardholder opened the account. `Format: YYYYMMDD`
- `account_change_indicator` '01' | '02' | '03' | '04' — Length of time since the last change to the cardholder account. This includes shipping address,
new payment account or new user added. Possible Values:
* 01 - Changed during transaction
* 02 - Less than 30 days
* 03 - 30-60 days
* 04 - More than 60 days
- `account_change_date` string, date — Date the cardholder's account was last changed. This includes changes to the billing or shipping address, new payment accounts or new users added.` Format: YYYYMMDD`
- `account_pwd_change_indicator` '01' | '02' | '03' | '04' | '05' — Length of time since the cardholder changed or reset the password on the account.
Possible Values:
* 01 - No change
* 02 - Changed during transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `account_pwd_change_date` string, date — Date the cardholder last changed or reset password on account. `Format: YYYYMMDD`
- `account_id` string — Additional cardholder account information.
- `account_purchases` integer — Number of purchases with this cardholder account during the previous six months.
- `acs_window_size` '01' | '02' | '03' | '04' | '05' — An override field that a merchant can pass in to set the challenge window size to display to the end
cardholder.The ACS will reply with content that is formatted appropriately to this window size to allow
for the best user experience. The sizes are width x height in pixels of the window displayed in
the cardholder browser window. Possible values:
* 01 - 250x400
* 02 - 390x400
* 03 - 500x600
* 04 - 600x400
* 05 - Full page
- `add_card_attempts` integer — Number of add card attempts in the last 24 hours.
- `address_match` 'Y' | 'N' — Indicates whether cardholder billing and shipping addresses match.
Possible Values:
* Y - Shipping address matches billing address
* N - Shipping address does not match billing address
- `alternate_authentication_method` '01' | '02' | '03' | '04' | '05' | '06' — Mechanism used by the cardholder to authenticate to the 3DS requester.
Possible Values:
* 01 - No authentication occurred (e.g. Guest Checkout)
* 02 - Login to the cardholder account at the Merchant system using Merchant system credentials
* 03 - Login to the cardholder account at the Merchant system using a Federated ID
* 04 - Login to the cardholder account at the Merchant system using Issuer credentials
* 05 - Login to the cardholder account at the Merchant system using third-party authentication
* 06 - Login to the cardholder account at the Merchant system using FIDO Authenticator
- `alternate_authentication_date` string, date — Date and time in UTC of the cardholder authentication. ` Format: YYYYMMDDHHMM`
- `alternate_authentication_data` string — Data that documents and supports a specific authentication
process that was sent in the AlternateAuthenticationMethod field.
- `threeds_contract_id` string, required — The ID of the threeDSContract used.
- `authentication_indicator` '01' | '02' | '03' | '04' | '05' | '06' — Indicates the type of Authentication request. 01 - Payment transaction
02 - Recurring transaction
03 - Installment transaction
04 - Add card
05 - Maintain card
06 - Cardholder verification as part of EMV token ID&V
- `category_code` integer — Merchant category code (MCC) NOTE: This field is required by Mastercard and VISA Brazil extensions.
- `challenge_indicator` '01' | '02' | '03' | '04' | '90' — NOTE: This is a 2.0 required field, Cardinal will default to 01 on Merchant Configuration
- can be overridden by the merchant. Possible Values:
* 01 - No preference
* 02 - No challenge requested
* 03 - Challenge requested (3DS Requestor Preference)
* 04 - Challenge requested (Mandate)
* 90 - CB specific value
- `delivery_email` string — For electronic delivery, email address to which the merchandise was delivered.
- `delivery_time_frame` '01' | '02' | '03' | '04' — Indicates the delivery timeframe.
Possible Values:
* 01 - Electronic delivery
* 02 - Same day shipping
* 03 - Overnight shipping
* 04 - Two or more day shipping
- `enabled` boolean — Whether 3DS should be used.
- `fraud_activity` '01' | '02' — Indicates whether the merchant experienced suspicious activity (including previous fraud) on the account.
Possible Values:
* 01 - No suspicious activity
* 02 - Suspicious activity observed
- `gift_card_amount` integer — The purchase amount total for prepaid gift cards in major units.
Example: $123.45 USD = 12345
- `gift_card_currency_code` string — ISO 4217 currency code for the gift card purchased.
- `gift_card_count` integer — Total count of individual prepaid gift cards purchased.
- `installment` number — Indicates the maximum number of authorizations for installment payments. An integer value greater than 1 indicating the maximum number of permitted authorizations for installment payments. ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `message_category` '01' | '02' — Category of the message for a specific use case.
Possible Values:
* 01 - PA (payment)
* 02 - NPA (non payment)
NOTE: Default is payment (01). Configured on Merchant account, or can be overridden on transaction.
- `payment_use_case` '01' | '02' | '03' | '04' | '05' — Indicates the type of payment.The value from this field will be mapped to the data field on the CB-USECASE extension
Possible Values:
* 01 - Single Payment
* 02 - Fixed Amount and Term Subscription
* 03 - Payment By Instalments
* 04 - Payment By Shipment
* 05 - Other Recurring Payments
NOTE: Required for CB transactions (Required if message_category = 01, or message_category = 02 and authentication_indicator = 02 or 03
- `payment_account_indicator` '01' | '02' | '03' | '04' | '05' — Indicates the length of time that the payment account was enrolled in the merchant account.
Possible Values:
* 01 - No account (guest checkout)
* 02 - During the transaction
* 03 - Less than 30 days
* 04 - 30-60 days
* 05 - More than 60 days
- `payment_account_age` string, date — Date the payment account was added to the cardholder account. ` Format: YYYYMMDD`
- `pre_order_indicator` '01' | '02' — Indicates whether cardholder is placing an order with a future availability or release date.
Possible Values:
* 01 - Merchandise available
* 02 - Future availability
- `pre_order_date` string, date — Expected date that a pre-ordered purchase will be available. `Format: YYYYMMDD`
- `prior_authentication_data` string — This field carry data that the ACS can use to verify the authentication process
- `prior_authentication_method` '01' | '02' | '03' | '04' — Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.
* 01 - Frictionless authentication occurred by ACS
* 02 - Cardholder challenge occurred by ACS
* 03 - AVS verified
* 04 - Other issuer methods
- `prior_authentication_time` string, date — Date and time in UTC of the prior cardholder authentication. ` Format: YYYYMMDDHHMM`
- `prior_authentication_ref` string — This data element contains a ACS Transaction ID for a prior authenticated transaction.
For example, the first recurring transaction that was authenticated with the cardholder
- `product_code` 'PHY' | 'CHA' | 'ACF' | 'QCT' | 'PAL' — Merchant product code.
Possible Values:
* PHY - Goods/Service Purchase
* CHA - Check Acceptance
* ACF - Account Funding
* QCT - Quasi-Cash Transaction
* PAL - Prepaid Activation and Load
NOTE: This value defaults to PHY. This field can be used to override that value if applicable.
- `recurring_end` string, date — The date after which no further recurring authorizations should be performed. `Format: YYYYMMDD` ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `recurring_frequency` number — Conditional: Integer value indicating the minimum number of days between recurring authorizations. A frequency of monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months. Example: 6 months = 168 ** Required for Recurring and Installment transactions, when authenticationIndicator="02" & "03" **
- `reorder_indicator` '01' | '02' — Indicates whether cardholder is placing an order with a future availability or release date.
Possible Values:
* 01 - Merchandise available
* 02 - Future availability
- `requestor_id` string — This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID.
NOTE: This is a 2.0 value only and if passed will override the Requestor Name value that is,
configured on the Merchant's profile.
- `requestor_name` string — This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID.
NOTE: This is a 2.0 value only and if passed will override the Requestor Name value that is configured
on the Merchant's profile.
- `shipping_address_usage_indicator` '01' | '02' | '03' | '04' — Indicates when the shipping address used for transaction was first used.
Possible Values:
* 01 - This transaction
* 02 - Less than 30 days
* 03 - 30-60 days
* 04 - More than 60 days
- `shipping_address_usage_date` string, date — Date when the shipping address used for this transaction was first used.
`Format: YYYYMMDD`
- `shipping_method_indicator` '01' | '02' | '03' | '04' | '05' | '06' | '07' — Indicates shipping method chosen for the transaction.
Possible Values:
* 01 - Ship to cardholder billing address
* 02 - Ship to another verified address on file with merchant
* 03 - Ship to address that is different than billing address
* 04 - Ship to store (store address should be populated on request)
* 05 - Digital goods
* 06 - Travel and event tickets, not shipped
* 07 - Other
- `shipping_name_indicator` '01' | '02' — Indicates if the cardholder name on the account is identical to the
shipping name used for the transaction. Possible Values:
* 01 - Account and shipping name identical
* 02 - Account and shipping name differ
- `total_items` string — Total items in the shopping cart of the shopper
- `merchant_score` string — Merchant score
- `transaction_count_day` integer — Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.
- `transaction_count_year` integer — Number of transactions (successful or abandoned) for this cardholder account within the last year.
- `transaction_mode` 'M' | 'P' | 'R' | 'S' | 'T', required — Transaction mode identifier. Identifies the channel the transaction originates from. Available Options:
M - Moto (Mail Order Telephone Order)
P - Mobile Device
R - Retail (Physical Store)
S - Computer Device
T - Tablet Device
- `version` '1.0.2' | '2.1.0' | '2.2.0' — This field contains the 3DS version that can be leveraged to force a transaction down the 1.0 rails.
- `authorization_type` string — Default: "FINAL_AUTH"
Other Possible Values: "PRE_AUTH"
Text: PRE_AUTH is used when a merchant wants to ensure shopper's funds availability at a later time.
Attention: If you are using PRE_AUTH function make sure capture_now is set as FALSE. Otherwise the PRE_AUTH will not work.
- `shopper_interaction` 'ECOMMERCE' | 'MAIL' | 'TELEPHONE' — Used to indicate the channel used by to send they checkout link
* ECOMMERCE
* MAIL - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
* TELEPHONE - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
- `payment_contract_id` string, required — This parameter can be found in the dashboard on the Payment Provider Contract attached to your organization. It is used to retrieve MID and other merchant configurations necessary for a card payment.
- `token_preference` TokenPreference — unresolved $ref
- `apple_pay` ApplePay — Apple Pay payment configuration
- `capture_now` boolean — True - transaction will be sent as authCapture and automatically captured.
False - transaction will be sent as auth and only authorized. NOT CAPTURED.
If you don't have any value in the capture_now parameter, at the moment of the call the value will be set as TRUE.
- `account_validation` boolean — Indicates whether the card transaction should be processed as Account Validation request instead. If set to true, the amount provided for the Checkout would be ignored and the transaction be processed with amount: 0
- `card` ApplePayCardConfig
- `sca_compliance_level` 'NONE' | 'WALLET' | 'FORCE_3DS', required — Strong Customer Authentication (SCA) compliance level, possible values * NONE: No SCA required. *Deprecated WALLET: Apple Pay will indicate the PSP to trigger 3DS which in this case will be required. Details [here](https://developers.google.com/pay/api/web/reference/response-objects#assurance-details-specifications) *Deprecated FORCE_3DS: SCA will be triggered. Regarding the liability shift, please check [this page](https://developers.googleblog.com/en/google-pay-enabling-liability-shift-for-eligible-visa-device-token-transactions-globally/) *Note: Apple Pay is SCA compliant by design and 3DS check is not a mandatory function for processing transactions with this wallet. As a result, the previously supported WALLET and FORCE_3DS parameters are no longer relevant for Apple Pay transactions and have been deprecated. Supports only NONE. Any other values (WALLET or FORCE_3DS) are sanitized and ignored.
- `threed_secure` object, required — Used for 3D-Secure payments
- `authorization_type` string — Default: "FINAL_AUTH"
Other Possible Values: "PRE_AUTH"
Text: PRE_AUTH is used when a merchant wants to ensure shopper's funds availability at a later time.
Attention: If you are using PRE_AUTH function make sure capture_now is set as FALSE. Otherwise the PRE_AUTH will not work.
- `shopper_interaction` 'ECOMMERCE' | 'MAIL' | 'TELEPHONE' — Used to indicate the channel used by to send they checkout link
* ECOMMERCE
* MAIL - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
* TELEPHONE - value is used only in Virtual terminal transactions and cannot be used in createCheckout API call
- `payment_contract_id` string, required — This parameter can be found in the portal on the Payment Provider Contract attached to your organization or given to you by a OnlinePay employee. It is used to retrieve MID and other merchant configurations necessary for a card payment.
- `token_preference` TokenPreference — unresolved $ref
- `expiry_time` string, date — Expiry time of the Checkout page. Defaults to 15 min from creation time. If a user tries to visit or use an expired Checkout, an error will be shown. Maximum value is 30 days.
- `merchant_reference` string — Reference provided by Merchant to identify the Checkout and the transaction initiated from it
- `return_url` string — URL belonging to the Merchant website, where the Customer would be redirected after the Checkout has been completed. If this parameter is used, the customer will be redirected after spending 10 seconds on the payment confirmation page provided by OnlinePay in case of HPP and PAYMENT LINK transactions. For IFRAME transaction the redirect is performed right after the checkout page without passing through the payment confirmation page.
Note 1: The return_url accepts only securely connected URLs i.e., via https protocol.
Note 2: The time after which redirection happens can be customized using redirect_method.
- `shop_url` string — URL belonging to the Merchant website, where the Customer would be redirected in case of cancelled Checkout.
Note: Only applicable to HPP or PAYMENT_LINK interaction type.
- `i18n` I18nConfiguration — Language preferences for the checkout page. Read Localisation for details.
- `default_language` string — Default language is used for displaying the page. Any customer language choice would override this option
- `fallback_language` string — Fallback language is used when DEFAULT_LANGUAGE is invalid. Any customer language choice would override this option
- `show_language_options` boolean — Indicates whether a language selection option should be shown to the customer on the Checkout page or not
- `interaction_type` 'HPP' | 'IFRAME' | 'PAYMENT_LINK' — Type of checkout. Allows for distinguishing payments accepted via different channels.
Possible Values:
* HPP - For payments done as Hosted Payments Page integration.
* IFRAME - For payments done as an Iframe integration.
* PAYMENT_LINK - For payments done through the Payment link feature in the merchant portal.
- `display_line_items` boolean — Indicates whether line items should be displayed on the page. Defaults to true
- `line_items` LineItem[] — List of shopping cart items to be displayed on the page. IMPORTANT: Please read the Line items documentation for required parameters depending on your payment methods.
- `image_url` string — Image URL for the line item
- `item_url` string — Item URL for the line item
- `name` string, required — Descriptive name of the order line item
- `quantity` integer — Quantity of the order line item
- `unit_price` number — Unit Price
- `unit_price_tax` number — Unit Price Tax
- `tax_rate` number — Additional details specific to this type of event
- `total_tax_amount` number — Total tax amount
- `total_amount` number, required — Total Amount
- `sku` string — The stock keeping unit (SKU) for the item.
- `description` string — The detailed item description.
- `category` 'DIGITAL_GOODS' | 'PHYSICAL_GOODS' — The item category type.
The possible values are:
* DIGITAL_GOODS - Goods that are stored, delivered, and used in their electronic format.
* PHYSICAL_GOODS - A tangible item that can be shipped with proof of delivery.
- `theme_id` string — Parameter that was created within the create theme API call that applies the customizations upon the checkout interface. Read Theming for details.
- `receipt_type` 'INVOICE' | 'FULL_RECEIPT' | 'SIMPLE_RECEIPT' | 'INVOICE_RECEIPT' — Can be used to send different invoices to the customer.
Possible Values:
* INVOICE
* FULL_RECEIPT
* SIMPLE_RECEIPT
* INVOICE_RECEIPT
- `sales_description` string — General description of the document
- `sales_channel` 'ECOMMERCE' | 'MOTO' — Channel used to process transactions.
Possible Values:
* ECOMMERCE
* MOTO
For sales_channel MOTO, no card.shopper_interaction is needed to be sent for this option.
- `customer_details` CustomerDetails
- `billing` Billing
- `address_1` string — Customer's primary billing address information.
Note:Required for 3DS. Please refer to the 3D Secure API specification for the format requirements.
- `address_2` string — Customer's secondary billing address information.
- `address_3` string — Customer's third billing address information.
- `city` string — Customer's city on their billing address.
Note:Required for 3DS. Please refer to the 3D Secure API specification for the format requirements.
- `country_code` string — Customer's alpha 2 digit ISO 3166 country code. (e.g. United States = US)
Note:Required for 3DS. Please refer to the 3D Secure API specification for the format requirements.
- `first_name` string — Customer's first name. **Required** in case that companyName is not provided.
Note:Required for 3DS. Please refer to the 3D Secure API specification for the format requirements.
- `middle_name` string — Customer's middle name.
- `last_name` string — Customer's last name. **Required** in case that companyName is not provided.
Note:Required for 3DS. Please refer to the 3D Secure API specification for the format requirements.
- `phone` string — Customer's phone number for billing address.
- `postal_code` string — Customer's postal code of their billing address.
Note:Required for 3DS. Please refer to the 3D Secure API specification for the format requirements. Required unless market or regional mandate restricts sending this information.
- `state` string — Customer's state or province of their billing address. (e,g. Ohio = OH, Texas = TX)
- `company_name` string — Company of the customer. . **Required** in case that billing.firstName & billing.lastName are not provided.
- `company_registration_number` string — Unique identifier of the company, recognised by the government. Known as CoC (Chamber of Commerce) number in some countries
- `email_address` string — Consumer's email address.
- `entity_id` string, required — Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)
- `phone_number` string — Cardholder's phone number
- `shipping` Shipping
- `address_1` string — Consumer's primary shipping address information. **Field required for**: Google Pay, Apple Pay
- `address_2` string — Consumer's secondary shipping address information.
- `address_3` string — Consumer's third shipping address information.
- `city` string — Consumer's city on their shipping address. **Field required for**: Google Pay, Apple Pay
- `first_name` string — Consumer's first name.
- `middle_name` string — Consumer's middle name.
- `last_name` string — Consumer's last name.
- `phone` string — Consumer's phone number.
- `country_code` string — Consumer's alpha 2 digit ISO 3166 country code. (e.g. United States = US) **Field required for**: Google Pay, Apple Pay
- `postal_code` string — Consumer's postal code of their shipping address. **Field required for**: Google Pay, Apple Pay
- `state` string — Consumer's state or province of their shipping address. (e,g. Ohio = OH, Texas = TX)
- `title` string — Title
- `work_phone` string — Consumer's work phone number.
- `tax` Tax
- `identifier` string — An optional identifier of the document recipient:
Personal ID (for individuals)
Tax identification number (for business)
- `tax_indicator` 'TAX_NOT_PROVIDED' | 'TAX_PROVIDED' | 'NON_TAXABLE' — Flag that indicates whether an order is taxable.
- `tax_amount` number — Total tax amount for all the items offers.
- `promo_code` string — A code defined by the merchant that affects the calculation of the total amount.
- `invoice_number` string — The invoice number to track this payment.
Note: Valid for card payments only.
- `allow_customer_inputs` boolean — Allows customer to enter or update their billing/shipping information on the hosted payments page.Only applicable for HPP and PAYMENT_LINK interaction types.
- `redirect_method` 'DEFAULT' | 'HEADER_REDIRECT' — Configures the redirect behaviour for return_url on successful payment when interaction type is either HPP or PAYMENT_LINK * DEFAULT: The customer will be redirected after spending 10 seconds on the payment confirmation page provided by Verifone. * HEADER_REDIRECT: The payment confirmation page is skipped and the customer is redirected immediately.
Note: This parameter does not have any effect when interaction type is IFRAME.
- `handle_order_confirmation` boolean — This change will remove the payment confirmation page from the user interface. Payment actions will now be managed through postMessage events.
Checkout Events:
* CHECKOUT_RENDERED: Indicates successful iFrame loading.
* CHECKOUT_RENDERED_FAILED: Signals iFrame loading failure.
* CARD_DETAILS_ENTERED: Triggered after the cardholder inputs card details.
* CHECKOUT_FAILED: Occurs when the checkout process encounters an error.
Payment Action listerer events:
* CONTINUE: Initiates the payment process.
**Note:** This parameter has no effect when the interaction type is HPP or PAYMENT_LINK.
- `show_confirmation_page` boolean — This change will remove the payment confirmation page from the user interface. Payment actions will now be managed through postMessage events.
Checkout Events:
* CARD_CAPTURE_SUCCESS: Indicates successful card capture.
* CHECKOUT_COMPLETED: Signals successful completion of the checkout process.
* CHECKOUT_FAILED: Occurs when the checkout process encounters an error.
**Note:** This parameter has no effect when the interaction type is HPP or PAYMENT_LINK.
- CardCaptureRequest
- `entity_id` string, required — Entity Id can be located on the organization level as Organization ID (Administration > Organizations > [Organization] > Organisation ID value)
- `customer` string — ID of a Customer created via the Customer API. A customer object can be created and attached to a Checkout. The customer object can store relevant customer details. Some of these details might be required, depending on the payment method and/or authentication mechanisms (e.g., 3DS) used in the Checkout
- `configurations` object, required
- `card` object — Card payment configuration
- `mode` 'CARD_CAPTURE'
- `card_capture_mode` 'v2' | 'v1' — Method of capturing card data. v2 is used by default as the recommended method. v1 is considered deprecated and is not supported for new integrations.
- `cvv_required` boolean — Indicates whether cvv is required
- `input_overrides` union
- InputOverrides — unresolved $ref
- Model2 — unresolved $ref
- `expiry_time` string, date — Expiry time of the Checkout page. Defaults to 15 min from creation time. If a user tries to visit or use an expired Checkout, an error will be shown. Maximum value is 30 days.
- `merchant_reference` string — Reference provided by Merchant to identify the Checkout and the transaction initiated from it
- `return_url` string — URL belonging to the Merchant website, where the Customer would be redirected after the Checkout has been completed. If this parameter is used, the customer will be redirected after spending 10 seconds on the payment confirmation page provided by OnlinePay in case of HPP and PAYMENT LINK transactions. For IFRAME transaction the redirect is performed right after the checkout page without passing through the payment confirmation page.
Note 1: The return_url accepts only securely connected URLs i.e., via https protocol.
Note 2: The time after which redirection happens can be customized using redirect_method.
- `shop_url` string — URL belonging to the Merchant website, where the Customer would be redirected in case of cancelled Checkout.
Note: Only applicable to HPP or PAYMENT_LINK interaction type.
- `i18n` I18nConfiguration — Language preferences for the checkout page. Read Localisation for details.
- `default_language` string — Default language is used for displaying the page. Any customer language choice would override this option
- `fallback_language` string — Fallback language is used when DEFAULT_LANGUAGE is invalid. Any customer language choice would override this option
- `show_language_options` boolean — Indicates whether a language selection option should be shown to the customer on the Checkout page or not
- `interaction_type` 'HPP' | 'IFRAME' | 'PAYMENT_LINK' — Type of checkout. Allows for distinguishing payments accepted via different channels.
Possible Values:
* HPP - For payments done as Hosted Payments Page integration.
* IFRAME - For payments done as an Iframe integration.
* PAYMENT_LINK - For payments done through the Payment link feature in the merchant portal.
- `theme_id` string — Parameter that was created within the create theme API call that applies the customizations upon the checkout interface. Read Theming for details.
- `sales_channel` 'ECOMMERCE' | 'MOTO' — Channel used to process transactions.
Possible Values:
* ECOMMERCE
* MOTO
For sales_channel MOTO, no card.shopper_interaction is needed to be sent for this option.
- `redirect_method` 'DEFAULT' | 'HEADER_REDIRECT' — Configures the redirect behaviour for return_url on successful payment when interaction type is either HPP or PAYMENT_LINK * DEFAULT: The customer will be redirected after spending 10 seconds on the payment confirmation page provided by Verifone. * HEADER_REDIRECT: The payment confirmation page is skipped and the customer is redirected immediately.
Note: This parameter does not have any effect when interaction type is IFRAME.
## Response `200`
Successful
- object
- `id` string, required — Checkout ID
- `url` string — URL of the Checkout
- `details` object — The details object displays any errors or warnings that occur during the request.
- `errors` object[]
## Other responses
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error
- `504` — Gateway Time-out
---
[API](https://skmtc.dev/westpac/apis/checkout-api.md) · [All operations](https://skmtc.dev/westpac/apis/checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/westpac/checkout-api/revisions/97b34ca7df9a/schema)