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":  "[email protected]",
    "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":  "[email protected]",
    "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":  "[email protected]",
      "reasonForRefund":  "Nada"
    },

    {
      "id":  11,
      "refundReference":  "kjsd313sjdsyegdie9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484145519777,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766904267,
      "createdBy":  "[email protected]",
      "reasonForRefund":  "Nada"
    },

    {
      "id":  10,
      "refundReference":  "kjsd313sdfafugidewK0e9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484121082547,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766903863,
      "createdBy":  "[email protected]",
      "reasonForRefund":  "Nada"
    },
    {
      "id":  9,
      "refundReference":  "kjsd31324KJDSK0e9322saud0q",
      "parentPaymentId":  3077027,
      "parentTransactionReference":  "172ea8e8-7070",
      "refundType":  "PARTIAL",
      "refundAmount":  1000,
      "createdDate":  1484006400000,
      "merchantCustomerId":  "RefundCustomer",
      "refundStatus":  "FAILED",
      "processedDate":  1487766903863,
      "createdBy":  "[email protected]",
      "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":  "[email protected]",
      "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":  "[email protected]",
  "reasonForRefund":  "Nada"
}

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

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

ON THIS PAGE

Introduction
- Sample Requests
- Response Code
Authentication
- Application Authorization
Creating a Refund Transaction
Get Refund Info
- Get Refund By MerchantCode and Date
- Get Refund by RefundReference and MerchantCode