Introduction

The Purchase API is designed to create a refund request from details of a successful transaction. This documentation describes how a third-party will integrate with the API and gain indepth knowledge about all the components of the API and how they interrelate.

Sample Requests

The Refund APIs are HTTP based RESTful APIs therefore API request and response format are in JSON. We have provided sample request and responses next to each endpoint in this documentation. All you need to do is replace the dummy parameters with yours.


BASE URL (Sandbox)

https://sandbox.interswitchng.com

BASE URL (Production)

https://passport.interswitchng.com

Response Code

Please refer to the standard HTTP response codes. Where anything starting with 2XX signifies approved, 4XX means client error and 5XX indicates server error. When the response codes start with 4XX or 5XX, an error object will be returned to explain further the reason for this failure. Find common response code and its description below:

Code Description
60002 Refund amount greater than transaction amount
10400 Error creating refund: This refund reference has already been used.
10500 Error processing request, please try again.
404 Transaction not found for merchant
400 Error creating refund: refund amount greater than transaction amount
500 Could not validate refund.

Authentication

Authenticate your API calls by including your access token in the Authorization header of every request you make. Interswitch utilizes OAuth 2 to facilitate authorization and grants access to an application either on behalf of a user or on behalf of the application itself.

Application Authorization

To get an access token, create a project on the Interswitch Developer Console and obtain the Client ID and Secret Key of the project and encode the them using this format client_id:secret_key using base64encode. Copy the encoded value of your Client ID and Secret Key and make a call to the endpoint below with the Authorization header that contains the word Basic followed by a space and the base64-encoded value. Ensure that you use the Content-Type:application/x-www-form-urlencoded header and finally pass the grant_type=client_credentials in the body of the request.


Endpoint

POST

/passport/oauth/token

Sample Request

import requests
url = "https://sandbox.interswitchng.com/passport/oauth/token"
body = {"grant_type":"client_credentials"}
headers = {
    'authorization': "Basic SUtJQTFCNzU5M0M0NDAyQkM1RTAwQzQ2QUM4QjFDMUNDMEI4NUVFQkIwODg6c2VjcmV0",
    'content-type': "application/x-www-form-urlencoded"}
response = requests.request("POST", url, data=body, headers=headers)
print(response.text)
REQUEST PARAMETERS
Parameters Required Type Description
ClientId Yes String Application key. Navigate to `https://developer.interswitchgroup.com` for your application key
SecretKey Yes String Application secret. Navigate to `https://developer.interswitchgroup.com` for your application secret.
grant_type Yes String This must be set to client_credentials

Sample Response (Success)

{ 
  "access_token": "{Your access token}",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "profile",
  "merchant_code": "MX10003",
  "requestor_id": "123588975884",
  "client_name": "kL79ov",
  "payable_id": "359854",
  "jti": "19800d56-3ac6-44c2-b318-8f2ece419840"
}

Sample Response (Failure)

{ 
  "code": "Unauthorized",
  "description": "Bad credentials",
  "errors": null
}
RESPONSE PARAMETERS
Parameters Description
access_token A new access token that is used to authenticate against resources that belong to the app itself.
token_type Always bearer
expires_in The lifetime of the access token, in seconds

Authorization headers should be in the following format: Authorization: Bearer Encoded(clientId:secreteKey).


Creating a Refund Transaction

This is to create a refund transaction request from details of a successful transaction.

Endpoint

POST

/paymentgateway/api/v1/refunds

Sample Request

{
    "id":  10174,
    "refundReference":  "REFUND-1543818751-JB-MX187",
    "parentTransactionReference":  "HelloStores0001",
    "merchantCode":  "MX187",
    "parentPaymentId":  269089,
    "refundType":  "PARTIAL",
    "refundAmount":  22200,
    "createdDate":  1543818875243,
    "refundStatus":  "PENDING",
    "createdBy":  "1543818751@tigerlasers.com",
    "reasonForRefund":  "Reason for REfund!"
}
REQUEST MESSAGE DESCRIPTION
Parameter Data Type Max Length Required Description
refundReference String 100 characters False This is a unique identifier sent by the merchant to identify his refund. I propose they should be guided to append their merchant code as a prefix so as not to clash with some other merchant's ID. If this field is not provided, a randomly reference is generated.
parentTransactionReference String 100 characters True (False if parentPaymentId is supplied) The transaction reference of the initial payment.Please Note: This field is Optional if parentPaymentId supplied
parentPaymentId string 100 characters True (False if parentTransactionReference is supplied) The payemnt Id of the initial payment. This field is Optional if parentTransactionReference is supplied
refundType string 100 characters Conditionally True If populated, it should be either PARTIAL or FULL.If PARTIAL, the refundAmount should be passed.If FULL, the refundAmount does not need to be passed. The full transaction amount will be refunded.
refundAmount Integer Conditionally True The amount is in minor. If the refundType is PARTIAL, this field is mandatory. If the refundType is FULL, this field is not mandatory.
createdBy String 100 characters False The details of the user that initiated the refund.
reasonForRefund string 100 characters False Details of why a refund was requested.

Sample Response (Success)

{

    "id":  10174,
    "refundReference":  "REFUND-1543818751-JB-MX187",
    "merchantCode":  "MX187",
    "parentPaymentId":  269089,
    "refundType":  "PARTIAL",
    "refundAmount":  22200,
    "createdDate":  1543818875243,
    "refundStatus":  "PENDING",
    "createdBy":  "1543818751@tigerlasers.com",
    "reasonForRefund":  "Reason for REfund!"
}

Sample Response (Error)

{
  "code":  "60002",
  "description":  "refund amount greater than transaction amount",
  "errors":  null
}
RESPONSE MESSAGE DESCRIPTION
Parameter Description
id The refund ID in the DB.
refundReference The reference of the newly created refund
parentPaymentId The database ID
refundType PARTIAL or FULL, determined by the refund amount.
refundAmount The amount requested.
createdDate UNIX timestamp of when the request was created.
refundStatus The processing state of the refund request, this could be either: FAILED, PENDING, or SUCCESSFUL.
createdBy Details of the user who requested the refundUNIX timestamp of when the request was created.
reasonForRefund Details of the refund reason.
merchantCode The initiating merchant's code.

Get Refund Info

This section describes how to get a list of the refunds created by a merchant.

Get Refund By MerchantCode and Date

This is to get a paginated list of all the refunds created by a merchant, within a specified date.

Endpoint

GET

/paymentgateway/api/v1/refunds?merchantCode={merchantCode}&pageNum={number}&pageSize={number}&startDate={MM/DD/YYYY}&endDate={MM/DD/YYYY}

Sample Request

GET https://sandbox.interswitchng.com/paymentgateway/api/v1/refunds?merchantCode=MX187&pageNum=1&pageSize=100&startDate=11/01/2018&endDate=12/03/2018

Sample Response (Success)

{
  "count":  8,
  "content":  [
    {
      "id":  12,
      "refundReference":  "kjsd3138shdsauhdsgdie9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484147875893,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766904267,
      "createdBy":  "mecode@sharklasers.com",
      "reasonForRefund":  "Nada"
    },

    {
      "id":  11,
      "refundReference":  "kjsd313sjdsyegdie9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484145519777,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766904267,
      "createdBy":  "mecode@sharklasers.com",
      "reasonForRefund":  "Nada"
    },

    {
      "id":  10,
      "refundReference":  "kjsd313sdfafugidewK0e9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484121082547,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766903863,
      "createdBy":  "mecode@sharklasers.com",
      "reasonForRefund":  "Nada"
    },
    {
      "id":  9,
      "refundReference":  "kjsd31324KJDSK0e9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484006400000,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766903863,
      "createdBy":  "mecode@sharklasers.com",
      "reasonForRefund":  "Nada"
    },
    {
      "id":  7,
      "refundReference":  "kjsd313243u0e9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484006400000,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766903860,
      "refundTransactionReference":  "ksadjlnmdsakw3892",
      "refundTransactionResponseCode":  "Z1",
      "createdBy":  "mecode@sharklasers.com",
      "reasonForRefund":  "Nada"
    }
  ]
}

Sample Response (failure)

// When a refund is not found it, returns a HTTP 200 with the following in the response body.
 {
    "count":  0,
    "content":  []
 }

// For system errors, the following may be returned.
{
  "code":  "10500",
  "description":  "Error processing request, please try again",
  "errors":  null
}

// This error message is returned when the refund reference has already been used. 
{
    "code":  "10400",
    "description":  "Error creating refund: This refund reference has already been used",
    "errors":  null
}

Get Refund by RefundReference and MerchantCode

This is to get a particular refund by specifying its reference.

Endpoint

GET

/paymentgateway/api/v1/refunds?refundReference=(reference)

Sample Request

GET https://sandbox.interswitchng.com/paymentgateway/api/v1/refunds?refundReference=kjsd313sjdsyegdie9322saud0007

Sample Response (failure) 


// When a refund is not found it, returns a HTTP 200 with nothing in the response body.
 {
  "id":  12,
  "refundReference":  "kjsd3138shdsauhdsgdie9322saud0q",
  "parentPaymentId":  3077027,
  "parentTransactionReference":  "172ea8e8-7070",
  "refundType":  "PARTIAL",
  "refundAmount":  1000,
  "createdDate":  1484147875893,
  "merchantCustomerId":  "RefundCustomer",
  "refundStatus":  "FAILED",
  "processedDate":  1487766904267,
  "createdBy":  "mecode@sharklasers.com",
  "reasonForRefund":  "Nada"
}

// For system errors, the following may be returned.

{
  "code":  "10500",
  "description":  "Error processing request, please try again",
  "errors":  null
}