Make a payment

Making a point-of-sale payment in a host-to-host solution involves the following steps:

• Optional daily step: get an Acquirer Working Key (AWK). To accept payments that require online PIN verification with the issuer, you need to get a new AWK every day to protect the PIN during transfer. Note that this is not necessary for offline PIN verification, where the payment terminal verifies the PIN with the EMV chip on the card.

• Step 1: authorize the payment.

  • You make a POST request to the /pos/v#/payments endpoint.
  • We verify the card with the issuer, and return an API response with our PSP reference for the transaction, and the result: Authorised or Refused. If authorized, the issuer reserves the funds on the cardholder's account. This is also referred to as an authorization hold.
  • You pass the authorization response to the payment terminal, to show the result to the customer.

• Step 2: complete the payment.

  • If the issuer authorized the transaction and the terminal approved the transaction, you make a POST request to the /hosttohostpaymentgateway/v#/payments/{paymentPspsReference}/completions endpoint. This completes the authorization and enables capturing the payment.
  • You get the result in an AUTHORISATION webhook.

After the authorization completion succeeds, we capture the payment and settle the funds to your bank account. Payments are captured automatically immediately after completion, unless you set a different capture method.

Contactless transactions and PIN

Under PSD2 regulations, Strong Customer Authentication (SCA) is required for contactless point-of-sale payments if the amount is above the card verification method (CVM) limit. For payments below the CVM limit, SCA is required every fifth payment or if the cumulative amount of consecutive contactless payments is above a certain limit. This customer authentication is usually done through online verification of the PIN that the customer entered on the payment terminal.

When a contactless payment requires SCA, your authorization request is declined. This is sometimes referred to as a soft decline. You need to retry the authorization and in this second authorization request send the customer's PIN. See PIN verification for information on how the PIN is protected during transfer. The PSP reference for the second authorization is the PSP reference that you should use for the completion request. It is also the PSP reference to use for any authorization adjustment, manual capture, cancellation, or refund.

To check if PSD2 SCA applies to you, see our self-service guide. There are also other regulations that may apply.

Online PIN verification

To accept online PIN as card verification method (CVM), your authorization request needs to contain the PIN that the customer entered on your payment device. We will then check the PIN with the issuer.

To protect the PIN during transfer we share two keys with you:

• Zone Master Key (ZMK): an AES 128 symmetric key-encryption key that is valid for two years.
• Acquirer Working Key (AWK): a 3DES AES 128 key with a TR-31 key block. This key has a limited validity. Every 24 hours you need to get a new AWK through our Management API.

Handle these keys as follows:

• Inform your Adyen contact that you want to use PIN verification in your host-to-host integration. We will send you a ZMK and configure your account for getting AWKs.
• When you receive the ZMK from us, you load it in your HSM solution.
• Every day:
  1. You make an API call to get a new AWK from us. We encrypt the AWK using the ZMK.
  2. You load the new AWK in your HSM solution, and replace the previous AWK with this new key. You also keep track of the version number of the new AWK.
• When a customer verifies a payment with a PIN:
  1. You receive the enciphered PIN from your POS system.
  2. In your HSM solution, you translate the enciphered PIN under the AWK (decrypt and then re-encrypt using the AWK.)
  3. In the authorization request that you send to us, you include the resulting AWK-encrypted PIN and the version number of the AWK.

Optional daily step: Get an AWK

To retrieve a key to protect customer PINs during transfer:

1. Make sure that you know the ID of your company. If you do not know this ID, make a GET /companies request.

2. Make a GET /partners/{companyId}/pos/keys request.

   The response returns:

   Parameter	Description
   key	The AWK to encrypt the customer's PIN with.
   version	The version number of the AWK.

3. From the response:

   • Load the key in your HSM solution, replacing the previous AWK.
   • Save the version or load it into your HSM solution together with the new key. You need to specify the key version later in your authorization requests for PIN payments.

Step 1: Make a payment authorization request

After the customer has presented their card to your payment terminal, follow these steps:

1. If online verification is needed of the PIN that the customer entered, get the AWK-encrypted PIN and the AWK version:

   1. Make sure that the AWK for the day is loaded in your HSM solution, and you know the version of that AWK.

      You need to get a new AWK every day.

   2. In your HSM solution, translate the customer's PIN using the AWK.

2. Make a POST /hosttohostpaymentgateway/v#/payments request. The request must include the following required parameters:

   Field	Required	Type	Description
   amount		object	An object with amount information consisting of: currency (string): the three-character ISO currency code for the transaction. value (integer): the final amount of the transaction, in minor units (without a decimal point). For Quick Chip, where the customer inserts their card and removes it before the final amount is known, use emvData.tag9f02 to provide an initial amount in addition to the final amount.value. If you are using the surcharge feature, add the amount of the surcharge to the final amount.value.
   merchantAccount		string	The merchant account identifier that you want to process the transaction with.
   posEntryMode		string	A two-character code indicating how the card data was obtained, based on the first two characters of field 22 defined by the ISO 8583:1987 specification: 00 is Unknown 01 is Manual (keyed) entry or MKE 02 is Magnetic Stripe 03 is Barcode read 05 is ICC (Contact Chip), CVV may be checked 07 is Contactless Chip 90 is a Magnetic Stripe read from track 2 91 is Contactless magnetic stripe 95 is ICC, CVV may not be checked
   reference		string	Your unique reference for the transaction.
   terminalCapabilities		string	A 3-byte hex-encoded value representing terminal capabilities, in accordance with Annex A2 of EMV Book 4.
   terminalCountryCode		string	The country code of the terminal's location. Format: the two-letter ISO-3166-1 alpha-2 country code. Exception: QZ (Kosovo).
   terminalIdentification		string	8 bytes hex-encoded value representing the unique location of a terminal at a merchant. Equivalent to EMV tag 9F1C (8 ans).
   terminalType		string	Indicates the environment of the terminal, its communications capabilities, and its operational control. Equivalent to EMV tag 9F35.
   transactionSequenceCounter		integer	Counter maintained by the terminal that is incremented by one for each transaction. Equivalent to EMV tag 9F41.
   transactionDate		string	Transaction date and time in ISO 8601 format (YYYY-MM-DDThh:mm:ss.sssTZD).

   Depending on your use case and the transaction type, add more parameters as needed. Expand the sections below for the details.

   Optional parameters

   Optional parameters include authorization type, routing parameters, and shopper statement.

   Field	Required	Type	Description
   authorisationType		string	If not specified, the default FinalAuth is used. For pre-authorisation use PreAuth.
   accountType		string	Indicates the type of account selected on the terminal. Possible values are: 10 (savings), 20 (cheque), and 30 (credit).
   customRoutingFlag		string	Identifies or overrides the acquirer account to use for the transaction. If you need to process some payments with an acquirer different from a default one, contact our Support Team to configure custom routing flags for the acquirer accounts to use for specific payment methods.
   fallbackPosEntryMode		string	The POS entry mode that was tried initially but didn't succeed for technical reasons. A two-character code indicating how the card data was obtained, based on the first two characters of field 22 defined by the ISO 8583:1987 specification: 00 is Unknown 01 is Manual (keyed) entry or MKE 02 is Magnetic Stripe 03 is Barcode read 05 is ICC (Contact Chip), CVV may be checked 07 is Contactless Chip 90 is a Magnetic Stripe read from track 2 91 is Contactless magnetic stripe 95 is ICC, CVV may not be checked
   mcc		string	Four-digit Merchant Category Code (MCC). This represents the type of goods or services a business provides. If you have multiple MCCs, use this parameter to ensure the transaction is routed correctly.
   merchantTerminalIdentifier		string	Your unique identification of the payment terminal.
   mobilePos		object	An object with information about your mobile POS device. Consists of type (required, with values COTS for a mobile device or COTS_WITH_EXTERNAL_CARD_READER for a mobile device with external card reader) and pinOnGlass (PIN entry on a touch screen with values true or false).
   shopperStatement		string	Dynamic shopper statement to enable shoppers to easily identify your charges on their bank statement. Your account must be configured to support dynamic shopper statements. For instructions and information about the allowed characters and maximum length, see Transaction description. If you are a payment facilitator, specific scheme rules may apply to the format of the shopper statement. Contact our Support Team to configure your account for providing shopper statements by API.
   store		string	Identifier of the store processing the transaction.
   terminalAdditionalCapabilities		string	A 5-byte hex-encoded value representing additional capabilities of the terminal, in accordance with Annex A3 of EMV Book 4.

   Tokenization

   Tokenization parameters include authorization type, routing parameters, and shopper statement.

   In the body of the initial payment request include a recurring object with the following parameters.

   Field	Required	Type	Description
   shopperReference		string	Your reference to uniquely identify this shopper, for example user ID or account ID. Do not use personally identifiable information. Minimum length: three characters.
   recurringProcessingModel		string	Creates a recurring contract. Possible values are: CardOnFile, Subscription, or UnscheduledCardOnFile. We will create a token for later payments, and save the shopper reference and shopper email on our platform. See tokenization parameters.
   shopperEmail		string	Your unique reference for the transaction. Max. 80 characters.

   When you receive the PaymentResponse, save the following data in your back-end system:

   • recurringDetailReference: the token representing the shopper's payment method, for use in online recurring payments.

   • shopperReference: your unique reference for this shopper that you specified in the request.

     Optionally also keep the following card and shopper identifiers, for easier shopper recognition:

     • shopperEmail: the shopper's email address, if you specified that in the request.
     • alias: the card alias, if enabled.
     • PaymentAccountReference: a reference to the payment account that is linked to the shopper's card and/or NFC wallet.

Partial payment

To make a partial payment, you must include the following parameter in the authorization request.

Parameter	Required	Type	Description
allowPartialAuth		boolean	Set to true to asks the issuer to return an authorization for the available amount instead of declining the transaction. Contact our Support Team to configure your account to support partial authorization.

Split payment data

Payment splits are only valid in a platform model.

To split the payment between the platform and the platform user, include a splits array. If you do not know the split amounts yet, you can split at capture instead.

Parameter	Required	Type	Description
splits		array	Defines how to split the payment.

The sum of the split amounts must equal the amount.value of the payment. Each array item in the splits array represents a split and can include:

Parameter	Required	Type	Description
account		string	Unique identifier of the account where the split amount should be sent. This is required if type is BalanceAccount.
amount.currency		string	The three-character ISO currency code. If this value is not provided, the currency in which the payment is made will be used.
amount.value		string	The amount of the split, in minor units (without a decimal point).
description		string	A description of the split.
reference		string	Your reference for the split, which you can use to link the split to other operations such as captures and refunds, and to reconcile the split and the associated payment. A reference is required if type is BalanceAccount.
type		string	The type of split. Possible values: Default, PaymentFee, Commission, BalanceAccount, Remainder, Surcharge.

Surcharge

Payment brands, such as card schemes and debit network providers, charge a fee for accepting payments on their payment network. Usually, businesses include the costs for payment fees in the prices they charge. But in some countries/regions it is common to pass on these costs as a surcharge when the customer makes a payment.

It is important to understand that the Adyen surcharge feature does not enforce compliance with card network requirements and local regulations. It remains your responsibility to ensure compliance. See our Surcharge compliance guide for more information.

You can add a surcharge to a regular payment, or to a split payment in a platform model.

Surcharge with regular payment

To add a surcharge to an authorization request for a regular payment:

• Specify an additionalAmounts.surcharge object.
• Add the amount of the surcharge to the amount.value of the payment.

Parameter	Required	Type	Description
additionalAmounts.surcharge		object	An object with surcharge information consisting of: currency (string): the three-character ISO currency code for the transaction. value (integer): the amount of the surcharge, in minor units (without a decimal point).

The following partial example shows a surcharge of 10 cents added to an original amount of EUR 10.

Surcharge in a split payment

Payment splits are only valid in a platform model.

To add a surcharge to an authorization request for a split payment:

• Specify a splits array item of type Surcharge with the account that the surcharge should be booked to. See Split payment data for details.
• Add the amount of the surcharge to the amount.value of the payment.

The following partial example shows a EUR 620.10 authorization request, split into EUR 600.00 to be paid into the account holder's account, a surcharge of EUR 0.10 to be paid to the account holder's account, and EUR 20.00 commission to be paid to the platform.

Sub-merchant data

If you are a payment facilitator, card schemes require you to provide certain data about your sub-merchant with each transaction. That is because your sub-merchant is considered the Merchant of Record when a transaction is facilitated by you.

Parameter	Required	Type	Description
subMerchantData		object	Information about the sub-merchant.

Include the following information in the subMerchantData object:

Parameter	Required	Type	Description
id		string	Your ID for the sub-merchant. Max length: 15
name		string	The name of the sub-merchant. Max length: 22
street		string	The street in the sub-merchant's address. Max length: 60
city		string	The city in the sub-merchant's address. Max length: 13
country		string	The country/region in the sub-merchant's address, specified as the three-letter country code in ISO 3166-1 alpha-3 format.
state		string	The state or province as defined in ISO 3166-2. Required for Brazil, Canada, and the US. Max length: 2
postalCode		string	The postal code. Required for Brazil, Canada, Ireland and the US.
taxId		string	The tax ID of the sub-merchant: an 11-digit CPF or 14-digit CNPJ.
mcc		string	The sub-merchant's 4-digit Merchant Category Code (MCC).
phoneNumber		string	The phone number of the sub-merchant. Max length: 20.
email		string	The email address associated with the sub-merchant's account. Max length: 320. Required only in Brazil.

EMV transaction

In case of an Europay, Mastercard, Visa (EMV) transaction, include the following parameters:

Parameter	Required	Type	Description
cvmResults		string	Results of the Cardholder Verification Method performed, provided as a 3-byte hex-encoded value in accordance with Annex A4 of EMV Book 4. Corresponds to tag 9f34.
emvData		object	EMV chip data provided as tag values.

The emvData object can contain the following EMV data tags.

Field	Required	Type	Description
tag4f		string	Application Identifier. Use this tag if tag9f06 is not present.
tag50		string	Application Label
tag57		string	Track 2 Equivalent Data
tag5a		string	Application Primary Account Number
tag5f20		string	Cardholder Name
tag5f24		string	Application Expiration Date
tag5f28		string	Issuer Country Code
tag5f30		string	Service Code
tag5f34		string	Application PAN Sequence Number
tag5f57		string	Type of account selected on the terminal.
tag82		string	Application Interchange Profile
tag84		string	Dedicated File (DF) Name
tag8e		string	Cardholder Verification Method List
tag95		string	Terminal Verification Results
tag9a		string	Transaction Date
tag9b		string	Transaction Status Information
tag9f02		string	Amount Authorised. Optional. Use this tag to provide an initial placeholder amount for use cases like Quick Chip where the final amount.value can be different from this initial amount.
tag9f06		string	Application Identifier
tag9f07		string	Application Usage Control
tag9f08		string	Application Version Number
tag9f09		string	Terminal Application Version Number
tag9f10		string	Issuer Application Data
tag9f12		string	Application Preferred Name
tag9f19		string	Token Requestor ID
tag9f1e		string	A 8 bytes hex-encoded value with BCD mode representing the Interface Device Serial Number. Equivalent to EMV requirement 8 an.
tag9f21		string	Transaction Time
tag9f24		string	Payment Account Reference
tag9f26		string	Application Request Cryptogram
tag9f27		string	Cryptogram Information Data
tag9f36		string	Application Transaction Counter
tag9f37		string	Unpredictable Number
tag9f53		string	Transaction Category Code
tag9f6e		string	Form Factor Indicator
tag9f66		string	Terminal Transaction Qualifiers
tag9f7c		string	Customer Exclusive Data

MSR or MKE transaction

In case of a magnetic stripe (MSR) transaction or a Manual Key Entry (MKE) transaction, include the object corresponding to the transaction type.

Parameter	Required	Type	Description
mkeData		object	Only required for MKE transactions (entry mode 1). An object containing string values for the entered cardNumber, expiryMonth (two digits), and expiryYear (four digits).
msrData		object	Only required for MSR transactions (entry modes 2, 90, 91). An object containing a track2Data string with the track 2 card details.

MOTO transaction

Reach out to your Adyen Account Manager before attempting MOTO payments on the host-to-host endpoint. Additional compliance and security requirements apply.

Mail Order/Telephone Order (MOTO) payments refer to card not present transactions keyed directly into the payment device. Include the following parameters as part of a MOTO payment:

Parameter	Required	Type	Description
mkeData		object	Required for all MOTO transactions. An object containing string values for the entered cardNumber, expiryMonth (two digits), expiryYear (four digits), and optionally the cvc (three to four digits) of the card
shopperInteraction		object	Required to specify this field as "Moto" for all MOTO transactions.
avsData		object	Optional field to provide address details to be verified by the issuing bank. An object containing the strings houseNumber and zip.

Online PIN transactions

In case of a chip card transaction with PIN entry where the PIN needs to be verified online with the issuer, include the PIN and the EMV data.

Parameter	Required	Type	Description
encipheredPINData		string	The customer's PIN encrypted using the AWK. If using AES-based PIN encryption, the PIN value needs to be sent as a HEX string of 32 Characters. If using DES-based PIN encryption, the PIN value needs to be sent as a HEX string of 16 Characters.
keys		object	Required if encipheredPINData is specified. Contains: pinKeyVersion: a string with the version number of the AWK. pinBlockFormat: a single digit indicating the ISO PIN block format for the customer's PIN.

Level 2/3 enhanced schema data (ESD)

Level 2/3 enhanced scheme data (ESD) is for US domestic payments with Mastercard and Visa, and lets companies track how much is spent on their corporate cards and the amount of sales tax:

• Level 2 data is purchase and tax details for the payment.
• Level 3 data is level 2 data plus line item details such as product quantity and product description.

Before you start, ask your Adyen account manager to enable sending Level 2/3 data enhanced scheme data (ESD) in your authorization request.

To add Level 2/3 data in your authorization request, include an enhancedSchemeData object with the following fields:

Level	Field	Required	Type	Description
2 and 3	customerReference		string	The reference number to identify the customer and their order. Format: ASCII Max length: 25 characters Must not start with a space or be all spaces. Must not be all zeros.
2 and 3	totalTaxAmount		string	The amount of state or provincial tax included in the total transaction amount, in minor units. Format: Numeric Max length: 12 characters For L2 data: must not be all zeroes. Must not be all zeros.
3	destinationCountryCode		string	The three-letter ISO 3166-1 alpha-3 country code for the destination address. Format: ASCII Fixed length: 3 characters.
3	destinationPostalCode		string	The postal code of the destination address. Format: ASCII Max length: 10 characters Must not start with a space. For the US, it must be in five or nine digits format. For example, 10001 or 10001-0000. For Canada, it must be in 6 digits format. For example, M4B 1G5.
3	destinationStateProvinceCode		string	The state or province code of the destination address. Format: ASCII Max length: 3 characters Must not start with a space.
3	dutyAmount		string	The duty tax amount, in minor units. Format: Numeric Max length: 12 characters For example, 2000 means USD 20.00.
3	freightAmount		string	The duty tax amount, in minor units. Format: Numeric Max length: 12 characters For example, 2000 means USD 20.00.
3	orderDate		string	The order date. Format: ASCII Max length: 6 characters Format: ddMMyy
3	shipFromPostalCode		string	The postal code of the address where the item is shipped from. Format: ASCII Max length: 10 characters Must not start with a space or be all spaces. Must not be all zeros.For the US, it must be in five or nine digits format. For example, 10001 or 10001-0000. For Canada, it must be in 6 digits format. For example, M4B 1G5.
3	enhancedSchemeDataItems		object	Contains additional L3 data.

The enhancedSchemeData.enhancedSchemeDataItems object contains the following fields:

Level	Field	Required	Type	Description
3	productCode		string	The product code. Must be a unique product code associated with the item or service. This can be your unique code for the item, or the manufacturer's product code. Format: ASCII Max length: 12 characters Must not start with a space or be all spaces. For L3 data: can be zero. For example, 2000 means USD 20.00.
3	description		ASCII	A description of the item, that provides details about the purchase. For Visa transactions with level 3 ESD, the description must not be the same or very similar to your merchant name, or, consist only of common words like "product", or "service". Format: ASCII Max length: 26 characters Must not be a single character. Must not be blank. Must not be all special characters. Must not start with a space or be all spaces. Must not be all zeros.
3	quantity		string	The number of items. Must be an integer greater than zero. Format: Numeric Max length: 12 characters Must not start with a space or be all spaces.
3	unitOfMeasure		string	The unit of measurement for an item. Format: ASCII Max length: 3 characters Must not start with a space or be all spaces. Must not be all zeros.
3	commodityCode		string	The code that identifies the item in a standardized commodity coding scheme. There are different commodity coding schemes: Format: ASCII Max length: 12 characters Must not start with a space or be all spaces. Must not be all zeros. UNSPSC commodity codes HS commodity codes NAICS commodity codes NAPCS commodity codes
3	totalAmount		string	The total amount for the line item, in minor units. See Amount requirements for level 2/3 ESD to learn more about how to calculate the line item total. Format: Numeric Max length: 12 characters Must not start with a space or be all spaces. Must not be all zeros.
3	unitPrice		string	The unit price in minor units. Format: Numeric Max length: 12 characters Must not be all zeros. For example, 2000 means USD 20.00.
3	discountAmount		string	The discount amount, in minor units. Format: Numeric Max length: 12 characters For example, 2000 means USD 20.00.

Select the tabs to see some example authorization requests.

3. When you receive the authorization response, check the resultCode. If this is Authorised, save the pspReference. Also save your reference and other details that you need for reconciliation or for your particular business model.
   The response contains:

   Field	Description
   alias	A value that uniquely represents the shopper's card number (PAN), for shopper recognition use cases. You cannot use the alias for making payments. To get the alias and aliasType, in your Customer Area go to Developers > Additional data and select Include alias info.
   aliasType	The alias type of the credit card number. Allowed values: Default BinLetterRandomLastFour The alias type depends on your account configuration.
   authorisationCode	Non-zero value generated by the issuer for an approved transaction.
   authorisationResponseCode	Response code generated by the issuer. Equivalent to tag8a for chip transactions.
   emvData	EMV chip data. If present, contains: tag8a: Authorisation Response Code tag91: Issuer Authentication Data
   currentBalance	Returned for gift cards and other stored value cards. The currency and value in minor units of the funds stored on the card.
   reference	Your unique reference for the transaction, echoed from the request.
   paymentMethod	The payment method (card type) used in the transaction. You can include this in the shopper receipt.
   pspReference	Our unique identifier for the request. Save this value, because you need it for the completion request and for payment modifications like cancel or refund. You can also use it to look up the transaction in your Customer Area.
   resultCode	The current state of the transaction. See Result codes. Authorised indicates that the issuer approved the transaction.
   retrievalReferenceNumber	Returned for some payment methods. The Retrieval Reference Number (RRN) that identifies the original authorization and links it to subsequent messages, such as reversals. You can include the RNN in the shopper receipt.
   schemeTransactionId	Returned for some payment methods. The transaction ID (TID) returned by the card scheme. The TID identifies the original authorization and links it to subsequent messages, such as reversals. You can include the TID in the shopper receipt.
   systemTraceAuditNumber	Returned for some payment methods. The System Trace Audit Number (STAN) generated by the cardholder's bank. The STAN identifies the original authorization and links it to subsequent messages, such as reversals. You can include the STAN in the shopper receipt.
   avsResponseData	Returned for MOTO payments when AVS or CVC data is provided in the request. Contains the avsResult, cvcResult as well as avsResultRaw and cvcResultRaw if enabled in the additional data. See AVS responses and CVC response codes.

   If the resultCode is not Authorised, see Handle a failed authorization.

4. Pass the response to the payment terminal, to show the result to the customer.

If the issuer authorized the transaction, the transaction has the status AuthorisedPending in your Customer Area.

Handle a failed authorization

If an authorization is declined, use the following authorization response fields to determine the cause and decide on your next step:

• resultCode: Authorised, Refused, Error, or Cancelled.
• refusalReason: Adyen's mapped reason for the refusal. This is a generalization of similar refusal reasons from different card schemes.
• refusalReasonCode: a code corresponding to Adyen's mapped refusal reason.
• emvData.tag8a: the raw Authorisation Response Code (ARC) for a chip card transaction.
• authorisationResponseCode: the ARC for a transaction, corresponding to the raw response value.

Note that the ARC can differ depending on the card scheme, so in general it is not recommended to code against this field. But if you have a multiple-acquirer setup where your code is already based on variable ARC values, you can use the ARC to determine the authorization status.

Decryption error

If you sent the customer's PIN, refusalReason Not supported indicates a decryption error. For example, because the AWK and the AWK version number didn't match.

PIN required

Contactless transactions are sometimes declined because authentication by PIN is required. The response contains:

• refusalReason: Card requires online pin and refusalReasonCode: 33
  or
• refusalReason: Authentication required and refusalReasonCode: 38

The response may also contain a retryData object that any subsequent retries for the same transaction must echo back.

In this case:

1. Discard the PSP reference from the failed authorization.
2. Retry the authorization, but this time include the customer's AWK-encrypted PIN and the AWK version. Echo the retryData object from the failed authorization in this attempt.
3. If the authorization now succeeds, use the PSP reference from this second authorization in the URL for the completion request.

Step 2: Make a payment completion request

If the issuer authorized the payment, the terminal makes a decision to approve or decline the transaction. Some of the reasons why the terminal can decline an authorized transaction are: the customer removed the card too soon, the customer cancelled the payment on the terminal, the card is programmed to not accept transactions when specific conditions apply, and so on.

• If the terminal approved the transaction, you must send a completion request. Otherwise, you can’t capture the funds (either automatically or manually).

  If you don’t send a completion request, the authorization is cancelled automatically after 72 hours.

• If the terminal declined the transaction, you should send a cancellation request to lift the authorization hold on the cardholder’s account. Do not wait for the authorization to expire automatically.

Other things to note about the payment completion request are that it allows you to set a capture method for this specific transaction, and that it needs to contain certain tag values that the terminal calculated if the customer used a chip card.

1. Make a POST request to the /hosttohostpaymentgateway/v#/payments/{paymentPspsReference}/completions endpoint, where {pspReference} is the PSP reference you received in the payment authorization response.

   Specify the following parameters:

   Field	Required	Type	Description
   captureDelay		string	Possible values are: manual, immediate, or a whole number that indicates the delay in hours between completing the authorization and capturing the payment. For more information, see Capture methods. If not specified, the capture setting of your merchant account applies.
   merchantAccount		string	The merchant account identifier that you want to process the transaction with.
   reference		string	Your unique reference for the transaction. Max. 80 characters. If you include it, use the same reference that you provided in the payment authorization request.
   merchantTerminalIdentifier		string	Your unique identification of the payment terminal.
   emvData		object	Only for chip card transactions: EMV data provided as tag values.

   If the customer has presented a chip card, make sure the emvData object contains the following EMV data tags.

   Field	Type	Description
   tag95	string	Terminal Verification Results
   tag9b	string	Transaction Status Information
   tag9f07	string	Application Usage Control
   tag9f10	string	Issuer Application Data
   tag9f26	string	Application Request Cryptogram
   tag9f27	string	Cryptogram Information Data
   tag9f36	string	Application Transaction Counter
   tag9f37	string	Unpredictable Number
   tag9f4c	string	ICC Dynamic Number
   tag9f5b	string	Issuer script results

   Select the tabs to see some example completion requests.

2. When you receive the completion response, check the result code. The response contains:

   Field	Description
   pspReference	Our unique identifier for the completion request. Note that this is different from the PSP reference of the payment authorization that you are completing.
   resultCode	The status of the completion request. Received indicates your request is being processed.
   reference	If the completion request included your unique reference for the transaction, the reference is echoed in the response.

3. Wait for an AUTHORISATION webhook to learn the result of the payment after authorization and completion.

If completion of the authorization succeeded, the transaction has the status Authorised in your Customer Area.

See also