Generate Bulk Token Request (Sent from Third-party)
The following describes the important element required to be sent for a Bulk Generate Token request.
| S/N | Data Element (DE) | Description | |
| 1 | subscriberId | Mandatory | Customer ID. E.g. 2348012233220 |
| 2 | paymentMethodCode | Mandatory | A unique Identifier of payment instrument issuer e.g. GTMM, FBN. See Payment Methods in Appendix B |
| 3 | frontEndPartnerId | Mandatory | A unique Identifier of App developer e.g. GTMM. See Front End Partners in Appendix B |
| 4 | tokenLifeTimeInMinutes | Mandatory | The time this Paycode token should expire |
| 5 | channel | Mandatory | Paycode channel. This can either be ATM, POS, Agent and WEB. See Paycode Channels in Appendix B |
| 6 | 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 |
| 7 | ttid | Mandatory | Terminal Transaction ID. A unique generated id sent from the client application. |
| 8 | oneTimePin | Conditional | The one time PIN to be used to cashout Paycode at ATM. This value is Mandatory for ATM Cashout |
| 9 | secure | Conditional | This contains payment method code authorization information. This field is Mandatory if the payment method authenticated by PIN. |
| 10 | pinBlock | Mandatory | This contains the encrypted payment method PIN. This field is Mandatory if the payment method is authenticated by PIN. |
| 11 | macData | Mandatory | This contains the MAC of some sensitive data. This field is Mandatory if the payment method is authenticated by PIN. |
| 12 | referenceId | Mandatory | Unique reference id. To be used as unique identifier to each bulk token generation request. |
| 13 | beneficiaryNumber | Mandatory | Mobile number of token beneficiary |
| 14 | entries | Mandatory | This array contains the amount, beneficiaryNumber and oneTimePin for each token |
| 15 | batchSize | Mandatory | This shows the total number of token intended to generate. NB. Only a maximum of 10 token can be generated at a time. |
| 16 | additionalInfo | Mandatory | This contains a data field “type” to specify that the token is a bulk token request message |
| 17 | Type | Mandatory | Is a child element to additionalInfo and has a value of bulk. |
| 18 | clientId | Mandatory | Please refer to the Interswitch Service Authentication specification document. |
| 19 | signature | Mandatory | This is the SHA 512 encryption of clientId, clientSecret, referenceId and transaction date and time (YYMMDD) |
| 20 | sftpAuthData | Mandatory | See Appendix on how to calculate sftpAuthData. |
Sample Request (API)
| POST {context}/pwm/bulk/tokens
Content-Type: application/json [Other HTTP headers]… frontEndPartnerId: 455
{ “additionalInfo”: {“type”: “bulk”}, “amount”: “5000000”, “batchSize”: 10, “channel”: “ATM”, “defaultOneTimePin”: “1234”, “entries”: [ { “amount”: “500000”, “beneficiaryNumber”: “08021111111”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111112”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111113”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111114”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111115”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111116”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111117”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111118”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111119”, “oneTimePin”: “1234” }, { “amount”: “500000”, “beneficiaryNumber”: “08021111110”, “oneTimePin”: “1234” } ], “macData”: “95e8f80c61bfec738894d0589b4909f9bf94070325e5c89f0f4d885f9fa49d77”, “paymentMethodIdentifier”: “E192F3F3B3BA4596BC9704C44EA801BC”, “pinBlock”: “2f04079406b19df1”, “referenceId”: “ga323923o4702”, “secure”: “79758137bcde04327126b604391649caa5bbe5016aba5bff5553842c646bfc7040c5a310f6d89ceb4d4a0c9545dc3523035a19357c99d28c7ba3cab37939295d5e010c4246534594900f8c1a03fa41215bc554aa1ea09f06d5896200d44d09d347e7042298312088a9a8ed54ed29eecddb2ad750c74713e7591006827f7860faa4419ce9b12693e820d98ffb4394229fa7fbbf7556160cd1508ce3ada3c35aded6a0a0d625a7b86f79adbb1770492c86cf098654eb9ecfb7859130191ae5aaebe210cea3e2b8f41b5023c0da0e18212c84542c4e1e411759fce29f91c8c5f9806a6df3e23e2a86b08b088d3aa1c0f07e92258bc2be1662fda0d8f3704c655ec0”, “subscriberId”: “2348124888436”, “tokenLifeTimeInMinutes”: “1440”, “ttid”: “274” } |
Sample Request (SFTP)
| The SFTP request message contains the following in a comma separated file (csv) in the following order.
frontEndPartner,subscriberId,amount,channel,tokenLifeTimeInMinutes,defaultOneTimePin,batchSize,sftpAuthData,referenceId,clientId,signature 455,2348124888436,4000000,ATM,1440,5214,10,7FB54FFEE55335E615330789B23A9CA9276C8AAF8A188A16DE6F5854B9DCC6471002064A0DEB858F184F9F9FADF89D5580DAF3A45B9B17F57F5B654E4D96C6468E04C96DEE84433AAA6B59EE3ECB161DAEFDFEF112CBBF271227A0896CFB28B75E9561E939AACBC0A750442424C63534,444433322,IKIAEE38C24A363E4FC01DEBFBFE9F8DC1F4BCB2BC48,1968c2282f733e0875e820e37a1e3c0ea0cb3489747faf72836e7849f03f15e7db53cfb6c7473df37332793165d34da30780cdaa00aa9c0b3d2fc1d1ef73a8e8 entries beneficiaryNumber, oneTimePin, amount 11111111111, 4321,400000 22222222222, 1234,300000 33333333333, 2345,500000 44444444444, 1234,400000 55555555555, 4321,300000 66666666666, 1234,500000 77777777777, 4321,500000 88888888888, 1234,100000 99999999999, 4321,500000 10000000000, 4321,500000 |
6.2 Generate Bulk 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 | phoneNumber | This is the beneficiaryNumber of the recipient of the paycode. E.g. 08021111111 |
| 2 | paymentTokens | This contains an array of the phoneNumber, paycode (token), smsStatus, expiry and surcharge for each beneficiaryNumber generated. |
| 3 | payCode | This is the one-time access code. |
| 4 | smsStatus | This indicates if an sms containing the paycode has been sent to the beneficiaryNumber |
| 5 | expiry | This indicates how long the paycode has before it expires. This value is the same as the tokenLifeTimeInMinutes in the bulk token request message |
| 6 | surcharge | This is the amount to be charged for each paycode when the paycode is cashed out. |
| 7 | numberOfEntries | This is the number of paycodes successfully generated |
| 8 | errorDescription | This contains the error message. |
Successful Response (API)
| HTTP Status Code: 201
{ “numberOfEntries”: 10, “paymentTokens”: [ { “phoneNumber”: “08021111111”, “payCode”: “12601555803”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111112”, “payCode”: “12601531357”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111113”, “payCode”: “12601382917”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111114”, “payCode”: “12601216456”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111115”, “payCode”: “12607585608”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111116”, “payCode”: “12605587175”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111117”, “payCode”: “12605531312”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111118”, “payCode”: “12601247388”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111119”, “payCode”: “12601009445”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 }, { “phoneNumber”: “08021111110”, “payCode”: “12602530509”, “smsStatus”: “Not Sent”, “expiry”: “1440”, “surcharge”: 10000 } ] } |
Successful Response (SFTP)
Unsuccessful Response (API)
| HTTP Status Code: 401
{ “errors”: [ { “code”: “E50”, “message”: “PayCode is Required” } ], “error”: { “code”: “E50”, “message”: “PayCode is Required” } }
HTTP Status Code: 401
{ “errors”: [ { “code”: “400503”, “message”: “The referenced transaction does not exist” } ], “error”: { “code”: “400503”, “message”: “The referenced transaction does not exist” } }
|
| HTTP Status Code: 401
{ “errors”: [ { “code”: “10500”, “message”: “Cannot Validate Authentication Details” } ], “error”: { “code”: “10500”, “message”: “Cannot Validate Authentication Details” } }
|
| Comma separated value (.csv) response in the format below:
“batchReference”,”numberOfSuccessful”,”numberOfFailed”,”amountOfSuccessful”,”amountOfFailed”,”totalSurcharge” “44443332210”,”10″,”0″,”4000000″,”0″,”100000″ “successful” “beneficiaryNumber”,”amount”,”paycode”,”surcharge”,”expiry”,”entryId” “11111111111”,”400000″,”12602835748″,”10000″,”1440″,”1″ “22222222222”,”300000″,”12601563843″,”10000″,”1440″,”2″ “33333333333”,”500000″,”12601611857″,”10000″,”1440″,”3″ “44444444444”,”400000″,”12609056048″,”10000″,”1440″,”4″ “55555555555”,”300000″,”12603487190″,”10000″,”1440″,”5″ “66666666666”,”500000″,”12606730320″,”10000″,”1440″,”6″ “77777777777”,”500000″,”12607422938″,”10000″,”1440″,”7″ “88888888888”,”100000″,”12607344666″,”10000″,”1440″,”8″ “99999999999”,”500000″,”12601665820″,”10000″,”1440″,”9″ “10000000000”,”500000″,”12609444075″,”10000″,”1440″,”10″ “failed” “beneficiaryNumber”,”amount”,”errorDescription”,”entryId” |
Unsuccessful Response (SFTP)
“ERROR MESSAGE”
“Invalid Signature”