Send OTP
- Ope Adeoye
- Victor Irechukwu
With this service, the calling apps can instruct a provider via OnePipe to send an OTP to a specified phone number or customer_ref. The added benefit here is that in the event that a provider needs authorization details of the account to debit for the value of the SMS or whatever the transport protocol is (bank account, wallet, etc) this can be supplied to the provider.
Before you proceed: Please read this.
Commercial model
The Provider needs to send a share of income to the settlement account at the host; which will then be shared with OnePipe, host and ISO.
Settlement & fees model
Model | How it works |
|---|---|
Invoice | The host client will invoice the calling app periodically for all calls to the endpoint. |
Process flows
Sequence of calls
App calls
/transactwith the right auth detailsProvider responds with any of the completion codes
SuccessfulorFailed.To query the status of a transaction, the app can call
/transact/query
INTERFACE SPECIFICATION (APP → ONEPIPE)
Request (Transact)
{
"request_ref":"{{request_ref}}",
"request_type":"send_otp",
"auth": {
"type": "bank.account | card | wallet | msisdn",
"secure": "{{encrypted(bank account number | card details | wallet | msisdn)}}", //if payment should be collected realtime, it would be charged here
"auth_provider": "Beeceptor",
"route_mode": null
},
"transaction": {
"mock_mode": "live",
"transaction_ref": "{{transaction_ref}}",
"transaction_desc": "A random transaction",
"transaction_ref_parent": null,
"amount": 0,
"customer":{
"customer_ref": "{{customer_id}}",//the recipient of the OTP
"firstname": "Uju",
"surname": "Usmanu",
"email": "ujuusmanu@gmail.com",
"mobile_no": "234802343132"
},
"meta":{
"a_key":"a_meta_value_1",
"another_key":"a_meta_value_2"
},
"details": {
"type": "sms | ussd",
"app_name": "My App",
"expiry_mins": 5, //optional time in minutes (defaults to 5 mins)
"message": "Use {otp} as your one time password on demo app" //this is used when type is set to 'sms'
}
}
}
Response
{
"status": "Successful",
"message": "Please enter the OTP sent to 234*****4656",
"data": {
"provider_response_code": "00",
"provider": "Beeceptor",
"errors": null,
"error": null,
"provider_response": {
"delivery_status": "delivered | failed | pending | logged",
"cost": "1200",//in kobo
"expires_on": "yyyy-MM-dd-hh-mm-ss",
"ussd_code": "*347*022*2*99312#", //in case of ussd
"prompt_message": "Please enter the OTP sent to 234*****4656",
"reference": "000022200225154318222333334432",
"meta":{
"field_key":"field_value",
"field_key":"field_value"
}
}
}
}
Breakdown of the details object
For this service, the details object will be null.
Acceptable values for auth.type
Value | Description |
|---|---|
card | Takes card details. |
bank.account | Takes bank account. |
wallet | Takes a wallet ID for debit. |
Possible status response codes
For this service, these are the possible responses a client can receive
Status | Meaning |
|---|---|
Successful | Standard success code |
Failed | Standard failure code |
INTERFACE SPECIFICATION (ONEPIPE → PROVIDER MICRO SERVICE)
Read this closely.