Send SMS
- Ope Adeoye
With this service, the calling apps can instruct a provider via OnePipe to send an SMS to a specified phone number or customer_ref. This is a standard send SMS (or bulk SMS) service. The slight difference here is that in the event that a provider needs authorization details of the account to debit for the value of the SMS (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_sms",
"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 message, in 234 format
"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": {
"message_body": "Welcome to Lagos",
"message_title": "A title",
"sender_id": "AnID" //the sender ID on the SMS if supported by the provider
}
}
}
Response
{
"status": "Successful",
"message": "Transaction processed successfully",
"data": {
"provider_response_code": "00",
"provider": "Beeceptor",
"errors": null,
"error": null,
"provider_response": {
"delivery_status": "delivered | failed | pending",
"cost": "1200",//in kobo
"reference": "000022200225154318222333334432",
"meta":{
"field_key":"field_value",
"field_key":"field_value"
}
}
}
}
Breakdown of the details object
For this service, the details object will contain the message body and message title (for delivery mechanisms that support a title, e.g. push notifications)
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.