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. |
| 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).
NB: We recommend that the ttid and transactionRef have the same value.
Sample Request
| POST https://sandbox.interswitchng.com/api/v1/pwm/subscribers/{subscriberId}/tokens
Content-Type: application/json [Other Interswitch security headers]… Click on this link 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
{ “subscriberId”: “2348012233220”, “payWithMobileToken”: “57889026616”, “tokenLifeTimeInMinutes”: “60” } |
Unsuccessful Response
| HTTP Status Code: 400
{ “errors”: [ { “code”: “10400”, “message”: “Bad request” } ], “error”: { “code”: “10400”, “message”: “Bad request” } }
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” } ] } |