Introduction

This document describes how a third-party will request for a Paycode© Token form Interswitch. Note that all data formats and response definitions are in conformance with the REST standard.

Design Overview

A Paycode© transaction is the one which does not requires the transaction initiator to use a Physical card when he/she wants to pay for goods and/or services at a merchant shop. However, in order to make payment at the merchant shop, a Token must be generated. The subsequent sections show the message structure for Token generation.

Registering on Developer Console

  1. Navigate to Developer Console on https://developer.interswitchng.com
  2. Click on New App

Single Paycode

The single token generation request message generates only one one-time access code also known as token for a Paycode transaction at a merchant location.

Generate Token

A Generate Token message is a request to generate a one-time access code also known as token for a Paycode transaction at a merchant location. Please request the context URL from Interswitch.

Generate Token Request (Sent from Third-party)

The following describes the important element required to be sent for a Generate Token request.

S/N Data Element (DE)   Description
1 subscriberId Mandatory Customer ID. E.g. 2348012233220
2 paymentMethodTypeCode Mandatory The type of payment instrument e.g. MMO, QTA, VMP. See "Payment Method Type Codes" in Appendix B for more.
3 paymentMethodCode Mandatory A unique Identifier of payment instrument issuer e.g. GTMM, FBN. See Payment Methods in Appendix B
4 frontEndPartnerId Mandatory A unique Identifier of App developer e.g. GTMM. See Front End Partners in Appendix B
5 tokenLifeTimeInMinutes Optional The time this Paycode token should expire
6 payWithMobileChannel Mandatory Paycode channel. This can either be ATM,  POS, Agent and WEB. See Paycode Channels in Appendix B
7 providerToken +Conditional Mobile Money Transaction Authentication Token
8 amount Conditional Transaction amount.  If payWithMobileChannel is ATM, this is Mandatory, if it is POS the purchase amount (the amount entered during transaction with Paycode) cannot be higher than this value
9 ttid Mandatory Terminal Transaction ID. A unique generated id sent from the client application.
10 codeGenerationChannelProvider Optional The Service Provider for the Code Generation Channel. If this value is not sent, the Front End Partner will be assumed to be the Code Generation Channel Provider. A value should be sent if the Code Generation Channel provider is different from the From End Partner.
11 oneTimePin Conditional The one time PIN to be used to cashout Paycode at ATM. This value is  Mandatory for ATM Cashout
12 accountNo Conditional This is the account no of the subscriber. This value is Mandatory if subscriber will be auto-enrolled if not existing. This is only for clients who wish to auto-enroll on Interswitch mPin platform during Paycode generation.
13 accountType Conditional This is the account type of the subscriber. This value is Mandatory if subscriber will be auto-enrolled if not existing. This is only for clients who wish to auto-enroll on Interswitch mPin platform during Paycode generation. See account type codes in Appendix B.
14 codeGenerationChannel Mandatory This is used to indicate the channel where Paycode will be generated. See Appendix "Paycode Code Generation Channels" for valid channels.
15 Secure Conditional This contains payment method code authorization information. This field is Mandatory if the payment method authenticated by PIN.
16 pinData Conditional This contains the encrypted payment method PIN. This field is Mandatory if the payment method is authenticated by PIN.
17 macData Conditional This contains the MAC of some sensitive data. This field is Mandatory if the payment method is authenticated by PIN.
18 autoEnroll Conditional This holds a true or false value. "True" if an account holder is to be auto-enrolled if no mPin card is found, and "false" if the account holder is not to be auto-enrolled. This field defaults to "false" if no value is sent
19 transactionRef Conditional Unique transaction reference. To be used as unique identifier in call to cancel token. Must not contain any special character
20 beneficiaryNumber Conditional Mobile number of token beneficiary

If the Payment Method Issuer decides to use an OTP for authorization, the OTP value is sent in this field (ProviderToken).

Sample Request

POST https://sandbox.interswitchng.com/api/v1/pwm/subscribers/{subscriberId}/tokens

Content-Type: application/json

[Other ISW HTTP headers]...Click on word  link belowto see the header documentation

Link Access_token: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2FyZGxlc3Mtc2VydmljZSIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy...... frontEndPartnerId: WEMA {"ttid": "12345", "paymentMethodTypeCode": "MMO", "paymentMethodCode": "WEMA", "payWithMobileChannel": "ATM", "tokenLifeTimeInMinutes": "60", "amount": "50000", "oneTimePin":"1234", "codeGenerationChannel": "INTERNET_BANKING", "codeGenerationChannelProvider": "WEMA", "accountNo": "1234567890", "accountType": "10", "autoEnroll" : "true", "transactionRef":"12345"}

Generate Token Response (Sent from Interswitch)

The following describes the important data element required for a Generate Token response.

S/N Data Element (DE) Description
1 subscriberId Customer ID. E.g. 2348012233220
2 payWithMobileToken This is the Paycode token.
3 tokenLifeTimeInMinutes The time this Paycode token will expire

Successful Response - HTTP Status Code:  200

{"ubscriberId": "2348012233220", "payWithMobileToken": "57889026616", "tokenLifeTimeInMinutes": "60"}

Unsuccessful Response - HTTP Status Code: 400

{ "errors": [{ "code": "10400", "message": "Bad request"}], "error": { "code": "10400", "message": "Bad request" }}

Unsuccessful Response - HTTP Status Code: 403

{"error": { "code": "E24", "message": "Invalid authentication credentials: Timestamp out of window"}, "errors": [ {"code": "E24", "message": "Invalid authentication credentials: Timestamp out of window"}]}

Cancel Token

A Cancel Token message is a request to cancel/deactivate an already generated Token. Please request the context URL from Interswitch.

Cancel Token Request (Sent from Third-party)\ The following describes the important element required to be sent for a Cancel Token request.

S/N  Data Element (DE)    Description
1 transactionRef Mandatory Original Transaction Ref used in token generation call. E.g. 324555
2 frontEndPartner Mandatory Front End Partner ID sent in token generation call

Sample Request

| DELETE https://sandbox.interswitchng.com/api/v1/pwm/tokens

Content-Type: application/json

[Other ISW HTTP headers]...Click on this link  to see the documentation

"transactionRef": "999393939",

"frontEndPartner": "SET"

{

"transactionRef": "1333447463",\ "frontEndPartner": "SET" }

Cancel Token Request (Sent from Interswitch)

The following describes the important data element required for a Cancel Token response.

S/N Data Element (DE) Description
1 code Response code of the operation e.g. 00
2 Description Response message of the operation e.g. Success

Successful Response - HTTP Status Code:  200

{"code": "00", "description": "Successfully queued to be cancelled"}

Unsuccessful Response - HTTP Status Code: 401

{   "errors": [  {"code": "E50",   "message": "Transaction reference cannot be empty."}],   "error": {   "code": "E50",   "message": "Transaction reference cannot be empty."}}

Unsuccessful Response - HTTP Status Code:  403

 {"error": {   "code": "E24",   "message": "Invalid authentication credentials: Timestamp out of window" },  "errors": [ {"code": "E24",    "message": "Invalid authentication credentials: Timestamp out of  window" }]}

Get Token Status

A Get Token Status message is a request to get the details of an already generated Token. Please request the context URL from Interswitch.

Get Token Status Request (Sent from Third-party)\ The following describes the important element required to be sent for a Get Token Status request.

| S/N | Data Element (DE) |   | Description | |-----|-----|-----| | 1 | paycode | Mandatory | Token being queried | | 2 | subscriberID | Mandatory | Subscriber ID used in token generation |

Sample Request

GET https://sandbox.interswitchng.com/api/v1/pwm/info/{subscriberID}/tokens

Content-Type: application/json paycode : {paycode} [Other ISW HTTP headers]...Click on this linkto see the header documentation

Get Token Status Response (Sent from Interswitch)

The following describes the important data element required for a Get Token Status response.

S/N Data Element (DE) Description
1 channel Channel generated token is to be used on e.g. ATM
2 token Queried token
3 Code Response code of transaction e.g. "0"
4 Description Response message of transaction e.g. "Successful"
5 PaymentMethodCode A unique Identifier of payment instrument issuer e.g. GTMM, FBN. See Payment Methods in Appendix B
6 Surcharge Surcharge on transaction
7 PaymentMethodIdentifier Payment Method Identifier
8 PaymentMethodTypeCode The type of payment instrument e.g. MMO, QTA, VMP. See "Payment Method Type Codes" in Appendix B for more.
9 TokenLifeTimeInMinutes The time this Paycode token should expire
10 Amount Transaction amount.
11 SubscriberID Customer ID. E.g. 2348012233220
12 SettlementCode Code used for settlement of transaction
13 Status Status of queried token e.g. 0
14 FrontEndPartner A unique Identifier of App developer e.g. GTMM. See Front End Partners in Appendix B

Successful Response - HTTP Status Code:  200

{"channel": "ATM", "token": "1260591524", "code": "0", "description": "Successful", "paymentMethodCode": "VEC", "surcharge": "10000", "paymentMethodIdentifier": "E192F3F3B3BA4596BC9704C44EA801BC", "paymentMethodTypeCode": "QTA", "tokenLifeTimeInMinutes": "90", "amount": "500000", "subscriberId": "2348124888436", "settlementCode": "3LFANTA", "status": "0", "frontEndPartner": "455"}

Unsuccessful Response - HTTP Status Code: 401

{"errors": [ {"code": "E50", "message": "PayCode is Required"}], "error": { "code": "E50", "message": "PayCode is Required" }}

Unsuccessful Response - HTTP Status Code:  401

{"errors": [ {"code": "400503", "message": "The referenced transaction does not exist"}], "error": { "code": "400503", "message": "The referenced transaction does not exist"}}