Submit payments from your server

Overview

Once you have a Card Identifier either via your own form or via our drop-in checkout, you can submit a payment from your server to the Sage Pay gateway.

You will need to authenticate your call using HTTP Basic authentication.

For HTTP Basic authentication, you will need to combine into a string the “integrationKey:integrationPassword”. The resulting string will have to be encoded using Base64 encoding. The encoded string will have to be included in the Authorization header.

Step 1: Submit transaction request

For a basic transaction you just need to provide us with the following parameters in the request body:

Submit-transaction-request

curl https://pi-test.sagepay.com/api/v1/transactions \
-H "Authorization: Basic aEpZeHN3N0hMYmo0MGNCOHVkRVM4Q0RSRkxodUo4RzU0TzZyRHBVWHZFNmhZRHJyaWE6bzJpSFNyRnliWU1acG1XT1FNdWhzWFA1MlY0ZkJ0cHVTRHNocktEU1dzQlkxT2lONmh3ZDlLYjEyejRqNVVzNXU="  \
-H "Content-type: application/json" \
-X POST \
-d '{
 "transactionType": "Payment",
 "paymentMethod": {
     "card": {
         "merchantSessionKey": "<merchant-session-key>",
         "cardIdentifier": "<card-identifier>"
     }
 },
 "vendorTxCode": "demotransaction-<unique-suffix>",
 "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"
}

For a full list of parameters please check out the transactions resource in our API reference

Step 2: Handle transaction response

The response may differ depending on your 3-D Secure requirements but if no 3-D Secure authentication is required and the transaction is successfully authorised, you should receive a response similar to the one below:

{
    "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 status, statusCode, and statusDetail will provide you with information regarding the transaction outcome.

handle-transaction-response

Transactions with 3-D Secure

Transactions that require 3-D Secure authentication are a little more complicated because your customer has to be forwarded to their card issuer to authenticate themselves before a card authorisation can occur. When 3-D Secure authentication is required the response will be similar to the following:

{
  "statusCode" : "2007",
  "statusDetail" : "Please redirect your customer to the ACSURL to complete the 3DS Transaction",
  "transactionId" : "DFAF9D9A-CD17-A4DF-B5A0-D9A9D88E4468",
  "acsUrl" : "https://test.sagepay.com/mpitools/accesscontroler?action=pareq",
  "paReq" : "eJxVUstuwjAQvPcrolwrxXaeCC1GtBwaJEpUqlbqzXKsEkQeOElD/r7rkBTq087serw7a1he8pP1o3SdlcXCZg61l/wB3g9aqfVeyVYrDltV1+JbWVm6sF3KfD8MIopBFPrMC5lvc0hWb+rMYRTiqOMwIBNEBS0Pomg4CHl+il+5T2eB5wIZIeRKx2se+NT3woBdD6avNBQiV9y0UIk+VXkJZGBAlm3R6J7P3BDIBKDVJ35ommpOSNd1znjPkWUOxOSA3NpJWhPVqHXJUt7JD/+4kY+7NZOfdbQ76qSPN5vTV7FdADEVkIpGcZwdm6SexaI59eYujjrwIHLTBGeUUpztCqAyb6zuM/cMoMdaFXKaYkKgLlVZKKxAH/5iSFUt+d5sIxG9tU1ifNpQQG6jPL8Yn2WD1jFj8RAZvQztwd7ZIGgAEFNLxu2RcdEY/fsAv12RstM=",
  "status" : "3DAuth"
}

Next steps