Introduction

Introduction

This API enables the processing of payments in a flexible, customisable way; ideal for users that want full control over their checkout flow.

For a simpler way to integrate (without quite as much control), take a look at our Checkouts or Hosted solutions.

📘

Features

The following features are available today:

• Payments - Process a Primary Transaction, retrieve the state of an Existing Transaction or process a Secondary Transaction such as a void or refund
• Orders - Retrieve an Order and all related primary and secondary transactions
• Schedules - Create or manage a Payment Schedule, such as recurring subscription, or a payment to be taken on specific dates
• Links - Create or manage Payment Links - allowing you to send links that customers can click to pay invoices or bills
• Tokenization - Create or manage Payment Tokens - allowing you to avoid storing payment details and eliminate PCI Compliance concerns
• Verification - Verify a card or token prior to taking payment
• Currency Conversion - Perform Dynamic Currency Conversion on an amount between merchant and cardholder currency
• Information Lookup - Retrieve Card Information such as issuer and country

Use cases

Some example use cases for the payments api are:

• An enterprise merchant wanting to take payments on their website or app but needing full control over the payment flow
• Managing post authorisation actions such as pre-auth completion, or processing refunds and voids

Make your first API call

Prereqs - ensure the following has been completed:

• Complete the general Getting started guide and get your sandbox API Key

Using the API Reference:

The easiest way to make your first API call is to use the API Reference page 'try it!' feature as follows, which doesn't require use of the message signature:

• Enter your API Key in the top-right and make sure the 'sandbox' environment is selected
• In the request body, select type PaymentCardSaleTransaction
• Enter the following values
  • transactionAmount.total as 11.22
  • transactionAmount.currency as GBP
  • order.additionalDetails.receipts.type as cardholder (currently only required due to readme bug on either the 'cardholder' dropdown or 'lineWidth' 'default')
  • paymentMethod.paymentCard.number as 5204740000001002
  • paymentMethod.paymentCard.expiryDate.month as 10
  • paymentMethod.paymentCard.expiryDate.year as 45
  • paymentMethod.paymentCard.securityCode as 002
• Press the 'Try It!' button, you should see an example request as well as an actual response!

{
  "requestType": "PaymentCardSaleTransaction",
  "transactionAmount": {
    "total": "11.22",
    "currency": "GBP"
  },
  "paymentMethod": {
    "paymentCard": {
      "number": "520474******1002",
      "securityCode": "002",
      "expiryDate": {
        "month": "10",
        "year": "45"
      }
    }
  }
}

{
    "clientRequestId": "708657f9-5318-42ca-b538-b15ed43c8f2f",
    "apiTraceId": "Y5xUfwAmTCyv89UtXtZ4CQAAAGc",
    "ipgTransactionId": "84614636463",
    "orderId": "R-6716887e-132d-4cbf-ac29-5727124d1b0a",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "MASTERCARD",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "10",
                "year": "2045"
            },
            "bin": "520474",
            "last4": "1002",
            "brand": "MASTERCARD"
        },
        "paymentMethodType": "PAYMENT_CARD"
    },
    "country": "United Kingdom",
    "terminalId": "RC103954",
    "merchantId": "881111110000228",
    "transactionTime": 1671189631,
    "approvedAmount": {
        "total": 11.22,
        "currency": "GBP",
        "components": {
            "subtotal": 11.22
        }
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:833609:4614636463:PPX :827568",
    "schemeTransactionId": "MCA1220321216",
    "processor": {
        "referenceNumber": "084614636463",
        "authorizationCode": "833609",
        "responseCode": "00",
        "responseMessage": "Function performed error-free",
        "avsResponse": {
            "streetMatch": "NO_INPUT_DATA",
            "postalCodeMatch": "NO_INPUT_DATA"
        }
    }
}

To prove it worked, grab your ipgTransactionId value from the response and head to the Get Transaction endpoint. Enter the value into the transaction-id path parameter and press 'Try It!' again. You should see your transaction.

Alternatively, you can use our Postman Collection to make the calls and see how they look outside of our documentation, this also takes care of the message signature generation for you.

🚧

Production

Please note that in order to use the full feature-set of these APIs in production you must:

• Have an approved production API Key
• Be onboarded to our payment gateway
• Use a Message Signature in all requests

Additional Reading

From here, you should read the following pages to better understand some of the key concepts of the Payments API:

• Generating a Message Signature - a security mechanism required for any requests outside of our 'Try It!' feature, our Postman Collection includes some code to generate this
• Understanding the different Request Types - allows you to specify the type of transaction (sale, refund, cancellation etc.) and the payment method (credit or debit cart, digital wallet, SEPA, Paypal etc.) - we used the standard PaymentCardSaleTransaction above
• Review the 3-D Secure page to ensure transaction security, make the checkout process frictionless for your customer and allow our fraud systems to protect you more easily

Recipes