UK Gateway

This guide contains the required steps to process card payments through the API & Inject. The main payment actions that can be applied to card transactions will each be described here. A prerequisite is added to each section which is required in order to perform the action.

All examples are done with the minimum required fields, please view the API reference documentation to check up-to-date required fields. Always check the page of the connection you are using to process your payment, most connections have exceptions regarding which payment actions can be performed and other exceptions regarding the currencies, dynamic descriptor formatting, customer object requirements, etc.

Authorize

Post the following body to the /transaction endpoint:

{
  "account": "account.id",
  "amount": 1000,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
}

Notice that in the above example the capture_now field is set to false. This is the flag that is used to authorize a transaction. Setting this field to true would attempt to immediately capture the transaction, otherwise known as a sale.

If the transaction is authorized the response should contain the following field:

{
    ...
    "status": "AUTHORIZED"
    ...
}

 The transaction has now been authorized and can be voided or captured.

Void authorization

Voiding authorizations requires you to include the transaction id in the POST URL. The url should be formatted like so: https://sandbox.omni.verifone.cloud/transaction/id/void where id is replaced with the transaction id.

If the void is accepted by the acquirer the response should contain the following field:

{
    ...
    "status": "AUTHORIZATION_VOIDED"
    ...
}

 Your authorization has been successfully voided.

Capture

Capturing transactions requires you to include the transaction id in the POST URL. The url should be formatted like so: https://sandbox.omni.verifone.cloud/transaction/id/capture where id is replaced with the transaction id.

The body should contain the amount you would like to capture on the transaction. It is only possible to capture less than the authorized amount, it is currently not possible to perform multiple captures on the same authorization.

{
    ...
    "amount": "1000
    ...
}

 If the capture is accepted by the acquirer the response should contain the following field:

{
    ...
    "status": "SETTLEMENT_REQUESTED"
    ...
}

 The transaction has now been captured. Once the settlement files are received from the acquirer the transaction will change to the status SETTLEMENT_COMPLETED. It usually takes 1-3 days before the settlement files are received, this timeframe differs per acquirer.

With some acquirers it is also possible to void the capture request.

Void capture

Voiding authorizations requires you to include the transaction id in the POST URL. The url should be formatted like so: https://sandbox.omni.verifone.cloud/transaction/id/void_capture where id is replaced with the transaction id.

If the void is accepted by the acquirer the response should contain the following field:

{
    ...
    "status": "SETTLEMENT_CANCELLED"
    ...
}

 Your capture has been succesfully voided.

Authorize & Capture (Sale)

Capturing and authorizing a transaction works the same as a regular authorization with one small difference: The capture_now flag needs to be set to true.

Post the following body to the /transaction endpoint:

{
  "account": "account.id",
  "amount": 1000,
  "card": "card.id",
  "capture_now": true,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
}

If the transaction is authorized the response should contain the following field:

{
    ...
    "status": "SETTLEMENT_REQUESTED"
    ...
}

Account Verification ($0 Auth)

Account verification transaction works the same as a regular authorization with one small difference: The amount needs to be set to 0.

Account verification does not have amount, so there is no money to be moved out of the customer's card, which means that capture_now has to be set to false. Attempting to capture a previously processed account verification transaction or sending it as a sale would fail.

Account verification transactions cannot handle 3DS data provided with them.

Post the following body to the /transaction endpoint:

{
  "account": "account.id",
  "amount": 0,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
}

 Credentials on File (COF), storing credentials for a first time

A Credential on File transaction is a transaction in which a cardholder has explicitly authorised a card acceptor to store the cardholder's account information for future use. COF transaction can be sent as Authorisation, Sale or Account Verification. It is also possible to provide 3DS data to it. Flagging a transaction as initial COF is done by providing an additional parameter recurring in the createCardTransaction POST. This parameter indicates the type of contract and processing model to be used, which controls the way the stored credentials can be used in the future. The schema for initial COF transaction is as:

recurring: {
  "contract": "string",
  "processing_model": "string"
}

After successfully processing such transaction, the response will contain an additional field reference under the recurring object. This reference needs to be provided for all subsequent transactions in order to use the credentials stored by this initial one. A reference will only be generated when the transaction is processed successfully.

Usage

• Initial COF transactions can also be sent as shopper_interaction set to mail_order or telephone_order.

Examples

{
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "recurring": {
    "contract": "ONE_CLICK",
    "processing_model": "COF"
  }
}

{
  "_id": "1234567",
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "recurring": {
    "contract": "ONE_CLICK",
    "processing_model": "COF",
    "reference": "1234567"
  }
}

{
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "recurring": {
    "contract": "RECURRING",
    "processing_model": "SUBSCRIPTION"
  }
}

{
  "_id": "9876556789",
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "recurring": {
    "contract": "RECURRING",
    "processing_model": "SUBSCRIPTION",
    "reference": "9876556789"
  }
}

{
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "recurring": {
    "contract": "RECURRING",
    "processing_model": "UNSCHEDULED_COF"
  }
}

{
  "_id": "87654321",
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "recurring": {
    "contract": "RECURRING",
    "processing_model": "UNSCHEDULED_COF",
    "reference": "87654321"
  }
}

 Credentials on File (COF), using previously stored credentials

COF transaction using previously stored credentials works the same way as regular regular Authorisation or Sale. In the case that the shopper is present, 3DS data can also be provided. Flagging a transaction as subsequent COF is done by providing shopper_interaction with value cont_auth and an additional parameter recurring . This parameter is used to indicate the processing model and provide reference, which both need to match the initially processed transaction.

{
  "shopper_interaction": "cont_auth",
  ...
  "recurring": {
    "processing_model": "string",
    "reference": "string"
  }
}

Usage

Examples

{
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "shopper_interaction": "cont_auth",
  "recurring": {
    "processing_model": "COF",
    "reference": "1234567"
  }
}

{
  "_id": "1234567",
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "shopper_interaction": "cont_auth",
  "recurring": {
    "processing_model": "COF",
    "reference": "1234567"
  }
}

{
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "shopper_interaction": "cont_auth",
  "recurring": {
    "processing_model": "SUBSCRIPTION",
    "reference": "87654321"
  }
}

{
  "_id": "9876556789",
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "shopper_interaction": "cont_auth",
  "recurring": {
    "processing_model": "SUBSCRIPTION",
    "reference": "9876556789",
  }
}

{
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "shopper_interaction": "cont_auth",
  "recurring": {
    "processing_model": "UNSCHEDULED_COF",
    "reference": "87654321"
  }
}

{
  "_id": "87654321",
  "account": "account.id",
  "amount": 1234,
  "card": "card.id",
  "capture_now": false,
  "customer_ip": "string",
  "dynamic_descriptor": "dynamic_descriptor",
  "merchant_reference": "string",
  "user_agent": "string",
  "shopper_interaction": "cont_auth",
  "recurring": {
    "processing_model": "UNSCHEDULED_COF",
    "reference": "87654321"
  }
}