Versions Compared

Old Version 1

changes.mady.by.user Ope Adeoye

Saved on

compared with

New Version Current

changes.mady.by.user Ope Adeoye

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Overview

With this service, the calling app can request or initiate payment from a customer. Apps will collect authorisation details and forward to OnePipe to execute a debit, OnePipe will in turn forward to the provider’s dedicated implementation.

Commercial model

Providers will be required to settle monies collected to a designated account by the client bank, less their fees. The client bank will handle secondary settlement to the apps, less their own fee and OnePipe's.

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.

Settlement & fees model

...

Settlement & fees model

Polaris will transfer to the account of the app, less the agreed fees. Polaris will then credit the settlement account of the host client with the collected fees. At settlement, the Host client will debit the agreed fee from the settlement account and split with all relevant parties.

Model

How it works

Amount

The provider removes a percentage or flat fee from the amount as fee and settles the difference to the app owner (via the client).

Commission

The provider surcharges the payer with an extra fee and pays a share of that surcharge 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

  1. App of JS calls /transact with the right auth details

  2. Provider responds with WaitingForOTP or PendingValidation as may be required if not overridden

  3. App calls /transact/validate to supply OTP if needed

  4. Provider responds with any of the completion codes Successful or Failed.

  5. To query the status of a transaction, the app can call /transact/query

  6. Where the provider supports it, the app can call /transact/reverse to request a reversalTo receive available options for this service, apps can call /transact/options.

Gliffy
macroId
imageAttachmentIdatt32243723att156598533
macroId924eaa30-1fe2-458b-aa28-649484a3f42d
baseUrlhttps://onepipe.atlassian.net/wiki
a9d3d285-2916-4123-9e93-236a130f390fnameOnePipe 2.0 Polaris Collect Service
diagramAttachmentIdatt32210953att156598528
containerId32243713
timestamp1575317456451

Interface specification - apps

Request

Code Block
languagejson
{
  "request_ref":"{{request-ref}}", 
  "request_type":"collect",
  "auth": {
    "type": "bank.account", 
    "secure": "4if1oYEoHx5Kp+PZj6RibJlXbx8zIKkP",
    "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}}",
    	"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": null
  }
}

Response

Code Block
languagejson
{
  "status": "Successful",
  "message": "Transaction processed successfully",
  "data": {
    "provider_response_code": "00",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "charge_status": "Successful",
      "provider_auth_token": "uji876hht",
      "auth_token": "uji876hht",
      "paymentoptions": []
    }
  }
}
Info

Note that this service supports that the details object is null

155123761
timestamp1581866633269

Acceptable values for auth.type

Takes card details for debit.

Type

Description

card

bank.account

Takes bank account details for debit.

cash

Will simply flag the transaction, as awaiting transaction_notification

custom

Takes a unique transaction ref. This mode is for when OnePipe.js or some other UI processes the payment and passes in a ref for validation of the payment.

voucher

Takes a voucher code for debit.

airtime

Takes MSISDN and debits the airtime on it.

wallet

Takes a wallet ID for debit.

bank.transfer

Simply instructs the provider to generate bank transfer instructions.

...

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

null

N/A

N/A

Interface specification - Providers

Request

Code Block
languagejson
{
  "request_ref":"{{request-ref}}", 
  "request_type":"collect",
  "auth": {
    "type": "CARD | BANK.TRANSFER | AIRTIME | WALLET | BANK.ACCOUNT | CASH | VOUCHER | auth_token | provider_auth_token | custom", 
    "secure": "4if1oYEoHx5Kp+PZj6RibJlXbx8zIKkP",
    "auth_provider": "Beeceptor"
  },
  "transaction": {
    "mock_mode": "live", 
    "transaction_ref": "{{transaction-ref}}", 
    "transaction_desc": "A random transaction", 
    "transaction_ref_parent": "", 
    "amount": 10000,
    "customer":{
    	"customer_ref": "{{customer id}}",
    	"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": null,
    "client_info": {
        "name": "TrustPay",
        "id": null,
        "bank_cbn_code": null,
        "bank_name": null,
        "console_url": null,
        "js_background_image": null,
        "css_url": null,
        "logo_url": "https://trustpay.onepipe.io/img/trustpay_logo_console.png",
        "footer_text": "Brought to you by <strong>SunTrust Bank</strong>",
        "options": [
            "BANK.TRANSFER",
            "CARD"
        ],
        "primary_color": "#b37038",
        "secondary_color": "#b37038",
        "primary_button_color": "#b37038",
        "modal_background_color": "linear-gradient(147.44deg, #d8903c 26.99%, #e69921 74.1%)",
        "payment_option_color": "rgba(76, 61, 47, 0.08)",
        "payment_option_active_color": "rgba(31, 31, 31, 0.25)",
        "app_color": "#b37038"
    },
    "app_info": {
      "name": "VictorMotors",
      "id": "5cdab3332b7d4100015f0db4",
      "beneficiary_account_no": "0001137069",
      "extras": {/*this will contain an array of provider override settings*/}
    }
  }
}

Response

Code Block
{
  "status": "Successful",
  "message": "Transaction processed successfully",
  "data": {
    "provider_response_code": "00",
    "provider": "Beeceptor",
    "errors": null,
    "error": null,
    "provider_response": {
      "charge_status": "Successful",
      "provider_auth_token": "uji876hht",
      "auth_token": "uji876hht",
      "paymentoptions": []
    }
  }
}

Special notes for providers

...

Special notes

This is effectively Polaris bank forcing an NIP (or local transfer) out of the customer’s account into the app owner’s account. At the same time, the provider fires a second transaction to put the fees into the settlement account of Polaris.