With this service, the calling app can collect a payment and top up a customer’s wallet at the same time. It uses the authorisation details supplied by the customer as well as a code to (optionally) identify the wallet service. Apps will collect authorisation details and forward to OnePipe to execute a debit and topup, OnePipe will in turn forward to the provider’s dedicated implementation. Supported auth types vary by provider.

Before you proceed: Please read this.

Commercial model

Option 1: Providers will pay the commissions due the app directly to the app while OnePipe just charges a fee per API call.
Option 2: Providers send the due commission to OnePipe (via the host settlement account) for onward split with all parties.

Special configuration notes

All providers of this service should implement OTP, but support the configuration of otp_override such that based on this configuration, they could be instructed to bypass the OTP requirement for an app if they support such configuration.

Settlement & fees model

Depending on the provider implementation, this service supports any or both of the 2 models.

Model	How it works
Commission	The provider surcharges the payer with an extra fee and pays a share of that surcharge to the app owner, OnePipe and Client. Or, the provider doesn’t apply a surcharge but rather just pays a percentage of the amount as commission to the app owner, OnePipe and Client.
Invoice	The client will invoice the calling app periodically for all calls to the endpoint.

Process flows

Sequence of calls

App [optionally] calls /transact/options to get a list of sub-wallet types available by the provider
App calls /transact with the right auth details
Provider responds with WaitingForOTP or PendingValidation as may be required
App calls /transact/validate to supply OTP if needed
Provider responds with any of the completion codes Successful or Failed.
To query the status of a transaction, the app can call /transact/query
Where the provider supports it, the app can call /transact/reverse to request a reversal

Interface specification - (App → OnePipe)

Request (/transact)

{
  "request_ref":"{{request-ref}}", 
  "request_type":"fund_wallet",
  "auth": {
    "type": "bank.account | card | wallet | airtime | token", 
    "secure": "{{encrypted secure}}",
    "auth_provider": "Beeceptor",
    "route_mode":"provider | options | null"
  },
  "transaction": {
    "mock_mode": "live", 
    "transaction_ref": "{{transaction-ref}}", 
    "transaction_desc": "A random transaction", 
    "transaction_ref_parent": "", 
    "amount": 10000,
    "customer":{
    	"customer_ref": "{{customer id}}", //the wallet number to top up
    	"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": {
      "service_code": "{{code representing the wallet service}}"
    }
  }
}

Response (/transact)

{
  "status": "Successful",
  "message": "Transaction processed successfully",
  "data": {
    "provider_response_code": "00",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "payment_status": Successful | Failed | Processing",
      "fulfillment_status": "Succesful | Failed | Processing",
      "transaction_final_amount": 20000,//in kobo
      "transaction_fee": 5000,//in kobo
      "narration": "My narration",
      "reference": "000022200225154318222333334432",
      "meta":{
        "field_key":"field_value",
        "field_key":"field_value"
      }
    }
  }
}

Acceptable values for `auth.type`

Type	Description
card	Takes card details for debit.
bank.account	Takes bank account details for debit.
voucher	Takes a voucher code for debit.
airtime	Takes MSISDN and debits the airtime on it.
wallet	Takes a wallet ID for debit.

Possible response codes

For this service, these are the possible responses a client can receive

Response code	Meaning
Successful	Standard success code
Failed	Standard failure code
WaitingForOTP	To signify that this provider has requested an OTP from the customer and it should be supplied.
PendingValidation	To signify that this provider needs some extra information to be provided. The `response.message` will contain the prompt.

Breakdown of the details object

For this service, the details object will be set to null

Field	Description	Possible values
service_code	A unique code representing the wallet service	Varies. E.g. 0803

Interface specification - (OnePipe → Provider)

Read this closely.

Fund Wallet