With this service, the calling app can request the underlying provider to generate (and optionally send) an invoice to a customer for a specific payment or service. Apps will pass in the details of the items to be paid for as well as the payer’s details and any authorisation details that may be required. OnePipe will in turn forward to the provider’s dedicated implementation. Providers will be required to respond the details of the invoice generated and a link with which the App can access it digitally.

Before you proceed: Please read this.

Commercial model

Providers can bill the calling App for every invoice generated.

Settlement & fees model

As a result of the commercial model, this service only supports 1 fees model.

Model	How it works
Invoice	The 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 (or null as the case may be)
Provider responds with Successful or Failed as may be required
To query the status of a transaction, the app can call /transact/query

Interface specification - (App → OnePipe)

Request

{
  "request_ref":"{{request_ref}}", 
  "request_type":"send_invoice",
  "auth": {
    "type": "null", 
    "secure": "{{null}}", 
    "auth_provider": "OnePipe",
    "route_mode": null
  },
  "transaction": {
    "mock_mode": "live", 
    "transaction_ref": "{{transaction_ref}}", 
    "transaction_desc": "A random transaction", //description that shouldcarry to the invoice
    "transaction_ref_parent": null, 
    "amount": 0,//amoun expected to be paid
    "customer":{
    	"customer_ref": "{{customer_id}}",
    	"firstname": "Uju",
        "surname": "Usmanu",
    	"email": "ujuusmanu@gmail.com",//the recipient of the invoice
    	"mobile_no": "234802343132"//the recipient of the invoice
    },
    "meta":{
    	"a_key":"a_meta_value_1",
    	"another_key":"a_meta_value_2"
    },
    "details": {
      "invoice_number": "00001",//optional. Provider can generate one
      "due_date": "09-08-2020",
      "payment_items": [
        {
          "item_description": "A big blag bag",
          "item_code": "ITEM001",
          "item_amount": 2000000          
        },
        {
          "item_description": "A big blag bag",
          "item_code": "ITEM001",
          "item_amount": 2000000
        }
      ],
      "reminders": [
        {
          "reminder_date": "09-08-2020",
          "reminder_title": "It's been 8 days, pay up!"
          "reminder_message": "The quick brown fox jumps over the lazy dog"
        },
        {
          "reminder_date": "09-08-2020",
          "reminder_title": "It's been 8 days, pay up!"
          "reminder_message": "The quick brown fox jumps over the lazy dog"
        }
      ]      
    }
  }
}

Responses

{
    "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": "1500",//in kobo
              "invoice_number": "00001",
              "due_date": "09-08-2020",
              "amount_due": "150000",//in kobo
              "invoice_link": "http://pages.onepipe.io/p/7uL21J"
              "reference": "000022200225154318222333334432",
              "meta":{
            }
        }
    }
}

Note that this service supports that the details object is null

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

Breakdown of the details object

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

Field	Description
invoice_number	The calling App may set the invoice number
due_date	Expected payment date of the invoice
payment_items	An array of items that make up the invoice
reminders	An array of scheduled reminders - if the provider supports that functionality

Interface specification - (OnePipe → Provider)

Read this closely.

Send Invoice