Submit Payments from Your Server

On this page:

Overview

When you receive a Card Identifier using our Drop-in Checkout or your Own Form integration, you can submit the payment to the Opayo gateway from your server.

Note: Opayo offers you a range of additional transaction types, too.

Integration

You must:

  • Authenticate your call using HTTP Basic authentication.
  • Format the string as, 'integrationKey:integrationPassword' and encode it using Base64 encoding.
  • Included the encoded string in the Authorization header.

Step 1. Submit the transaction request

For a basic transaction, the parameters listed in the following table must be included in the request body.

Transaction request parameters

Property

Description

transactionType

The type of transaction requested. For example, Payment or Repeat.

paymentMethod

The payment method for the transaction. In this object you must provide us with the cardIdentifier and the merchantSessionKey used to create that cardIdentifier.

vendorTxCode

Your unique reference for this transaction.

amount

The amount in the smallest currency unit.
For example, to charge £1.00 the amount is input as 100. A Pound is 100 Pence. There is no smaller unit than the Pence.

currency

The currency of the amount in 3 letter ISO-4217 format. For example, GBP.

customerFirstName

Your customer's first name.

customerLastName

Your customer's last name.

billingAddress

Your customer's billing address.

Important: You must submit the strongCustomerAuthentication object. For more information, see the API reference.

Example payment transaction request

curl https://pi-test.sagepay.com/api/v1/transactions \ -H "Authorization: Basic aEpZeHN3N0hM..NVVzNXU=" \ -H "Content-type: application/json" \ -X POST \    -d '{
  "transactionType":"Payment",
  "paymentMethod":{
    "card":{
      "merchantSessionKey":"",
      "cardIdentifier":""
    }
  },
  "vendorTxCode":"demotransaction-",
  "amount":10000,
  "currency":"GBP",
  "description":"Demo transaction",
  "apply3DSecure":"UseMSPSetting",
  "customerFirstName":"Sam",
  "customerLastName":"Jones",
  "billingAddress":{
    "address1":"407 St. John Street",
    "city":"London",
    "postalCode":"EC1V 4AB",
    "country":"GB"
  },
  "entryMethod":"Ecommerce",    
  "strongCustomerAuthentication": {
        "website": "https://mydomain.com",
        "notificationURL": "https://notification.url",
        "browserIP": "10.68.21.21",
        "browserAcceptHeader": "text/html, application/json",
        "browserJavascriptEnabled": true,
        "browserJavaEnabled": false,
        "browserLanguage": "en-GB",
        "browserColorDepth": "16",
        "browserScreenHeight": "768",
        "browserScreenWidth": "1200",
        "browserTZ": "+300",
        "browserUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:67.0) Gecko/20100101 Firefox/67.0",
        "challengeWindowSize": "Small",
        "threeDSRequestorChallengeInd": "02",
        "requestSCAExemption": false,
        "transType": "GoodsAndServicePurchase",
        "threeDSRequestorDecReqInd": "N"
    }
}'

You can find a full list of parameters in our API Reference.

Step 2. Handle transaction responses

Responses depend on your 3D Secure requirements. When 3D Secure authentication is not required and the transaction is successfully authorised, you should receive a response similar to the following example:

{
  "transactionId":"T6569400-1516-0A3F-E3FA-7F222CC79221",
  "transactionType":"Payment",
  "status":"Ok",
  "statusCode":"0000",
  "statusDetail":"The Authorisation was Successful.",
  "retrievalReference":8636128,
  "bankResponseCode":"00",
  "bankAuthorisationCode":"999777",
  "paymentMethod":{
    "card":{
      "cardType":"Visa",
      "lastFourDigits":"0006",
      "expiryDate":"0317"
    }
  },
  "3DSecure":{
    "status":"NotChecked"
  }
}

The statusstatusCode and statusDetail inform you of the transaction outcome.

Response statuses

Status

Status description

OK

Transaction request completed successfully.

NotAuthed

Transaction request was not authorised.

Rejected

Transaction request was rejected by your fraud rules.

Malformed

Missing properties or badly formed body.

Invalid

Invalid property values supplied

Error

An error occurred at Opayo

Transactions with 3D Secure

Transactions that use 3D Secure authentication require your customer to be forwarded to their card issuer for authentication before a card authorisation can complete. When 3D Secure authentication is required you should receive a response similar to the following example:

{
  "statusCode":"2007",
  "statusDetail":"Please redirect your customer to the ACSURL to complete the 3DS Transaction",
  "transactionId":"DFAF9D9A-CD17-A4DF-B5A0-D9A9D88E4468",
  "acsUrl":"https://test.opayo.co.uk/mpitools/accesscontroler?action=pareq",
  "paReq":"eJxVUstuwjAQvPcrol.../fsAv12RstM=",
  "status":"3DAuth"
}

Next steps