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 /transact with the right auth details
Provider responds with any of the completion codes Successful or Failed.
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"
    }
  }
}

Response

{
    "status": "Successful",
    "message": "Transaction processed successfully",
    "data": {
        "provider_response_code": "00",
        "provider": "Beeceptor",
        "errors": null,
        "error": null,
        "provider_response": {
            "reference": "50617644717007",
            "delivery_status": "delivered",
            "cost": "1200",//in kobo
        }
    }
}

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.

Send SMS