This section helps the client build the External Authorization API. External Authorization API is a client-hosted API called by the Prepaid system whenever an auth transaction occurs for client approval (external authorizer).
Prerequisites
- Basis the approval/rejection from the client side, the response will be passed ahead with the network.
- The client should make this API available all the time and the response should be well within the timeout time.
- If the API does not respond withing the timeout time, then the issuer shall decline the transaction as timed-out.
- The timeout time at Wibmo Prepaid is 2000 milliseconds.
- The endpoint ending with <API_PATH> must be maintained by the client.
API / webhooks headers
Parameter | Type | Parameter Requirement | Description |
|---|---|---|---|
X-Consumer-Custom-ID | string (15) | Mandatory | This is the unique key to be shared with the client by Wibmo for the API environment exposure. |
clientId | string (15) | Mandatory | This is the Unique ID for the client to be shared by Wibmo. |
bankId | numeric (4) | Mandatory | Unique ID to identify the issuer bank. Wibmo to share. |
entityId | numeric (4) | Optional | Child corporate/branch entity ID under the client. If not passed, it will default to the client's parent branch. |
External authorization
API URL Path: api/v1/externalAuth
Type: POST
Request parameters
Parameter | Type | Parameter Requirement | Description | Sample value |
|---|---|---|---|---|
customerId | string(50) | Optional | Unique customer ID for the customer in the Prepaid and client system. | HRM0054454 |
urn | string(20) | Mandatory | Unique reference number for the customer. | 10000333 |
merchantName | string(50) | Optional | The Merchant name of the transaction | xyz |
terminalId | string(50) | Mandatory | Terminal ID | 1234 |
mcc | numeric(10) | Optional | Payee merchant category code | 5999 |
systemTraceAuditNumber | numeric(6) | Mandatory | STAN 6-digit unique internal audit number for the issuer | 162 |
cardNetwork | string(20) | Mandatory | Card scheme | RUPAY |
channel | string(10) | Mandatory | POS, ECOM, ATM, POS-Contactless | ATM |
merchantId | string(50) | Optional | Payee merchant ID | 12 |
transactionAmount | string(15) | Mandatory | Transaction amount in implied decimals. | 20000 |
fee | string(15) | Optional | Fee collected for the transaction in implied decimals. | 1000 |
transactionReferenceNumber | string(50) | Mandatory | Transaction Reference Number | 0200900780010618271700000123 |
currencyCode | string(3) | Optional | In ISO-4217 country currency code format. E.g., 356 for INR and 840 for USD | 356 |
last4Digits | string(4) | Mandatory | Last four digits of the card number | 8689 |
originalRrn | string(30) | Optional | RRN received from the network | 726474 |
billingCurrency | string(3) | Conditional | Billing currency code in ISO-4217 country currency code format. E.g., 356 for INR and 840 for USD | 356 |
billingAmount | string(15) | Conditional | Billing currency Amount in implied decimals. | 2000 |
Sample request
{
"fee": "1000",
"merchantName": "xyz",
"terminalId": "1234",
"mcc": 5999,
"systemTraceAuditNumber": 900780,
"entityId": "100",
"cardNetwork": "RUPAY",
"channel": "ATM",
"merchantId": "12",
"transactionAmount": "200000",
"transactionReferenceNumber": "0200900780010618271700000123",
"urn": "611930",
"currencyCode": "356",
"last4Digits": "1234",
"orignialRrn": "726474",
"customerId": "IN2016201611",
"billingCurrency": "356",
"billingAmount": "200000"
}Response parameters
| Parameter | Type | Parameter Requirement | Description | Sample value |
|---|---|---|---|---|
| responseCode | string(5) | Mandatory | Response code as per the API response code table. | 00 |
| responseDescription | string(100) | Mandatory | Response description based on the responseCode. | TRANSACTION_APPROVED |
| responseDateTime | numeric(14) | Mandatory | Response timestamp in the format YYYYMMDDHHMMSS with time in 24 hr format. | 20161031214559 |
| transactionAmount | string(15) | Mandatory | Transaction amount. | 20000 |
| currencyCode | string(3) | Mandatory | Echoed from the request. | 356 |
Sample response
{
"transactionAmount": "200000",
"currencyCode": "356",
"responseCode": "00",
"responseDescription": "TRANSACTION_APPROVED",
"responseDateTime": "20161031214559"
}Response codes
Note:
A proper response code should be sent in the response from the client. In case of any other scenario from the codes mentioned in the following table, `05` should be passed by default.
| Response code | Response description |
|---|---|
00 | TRANSACTION_APPROVED |
05 | DO_NOT_HONOR |
14 | CARD_NOT_FOUND |
34 | SUSPECTED_FRAUD |
41 | LOST_CARD |
43 | STOLEN_CARD |
51 | NO_SUFFICIENT_FUNDS |
61 | EXCEEDS_WITHDRAWAL_AMOUNT_LIMIT |
65 | EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT |