![\"The](\"http://www.onepipe.io/docs/principles.jpg\")
This suite of APIs provides access to an array of payment-related services like card charging, airtime, bill payment, instant loans and KYC lookup services. Some of these services come from multiple providers like Interswitch, Flutterwave and Paystack, but OnePipe wraps around them an abstraction layer with one major goal: To provide a consistent interface to integrators regardless of underlying service provider. That way, you can switch between providers at any time, based on quality of service, business justification, etc. without starting a new integration project or changing your systems in any way.
\nFast try
\nhttps://409a9dcf-73e5-41bb-aa2e-ba6c286173a3.mock.pstmn.ioActual transactions
\n
Here's the list of services versus providers available at the moment. It's a list that will grow with time as we complete more integrations.
\nProvide card details, OnePipe forwards to selected provider, provider debits the linked account. The underlying provider may prompt for OTP, therefore you’d supply the OTP via a follow-on call. If a charge is successful, you’d get back a charge-token with which you can initiate future transactions without providing card details afresh. Providers are:
\nProvide card details, mobile number and network. OnePipe forwards to selected provider, provider debits the linked account and credits the attached number with airtime. The underlying provider may prompt for OTP, therefore you’d supply the OTP via a follow-on call. If a transaction is successful, you’d get back a charge-token with which you can initiate future transactions without providing card details afresh. Providers are:
\nProvide card details, customer id and a biller code. OnePipe forwards to selected provider, provider debits the linked account and makes the payment to the biller code provided. The underlying provider may prompt for OTP, therefore you’d supply the OTP via a follow-on call. If a transaction is successful, you’d get back a charge-token with which you can initiate future transactions without providing card details afresh. Providers are:
\nAfter verifying a customer’s mobile number, provide same number and OnePipe will forward to underlying provider to evaluate what loan amounts (short term, instant loans) can be extended to the user. Customer selects one of the offers and you can forward back to the provider via OnePipe for the provider to credit the account. Usually instantly. Providers are:
\nAfter verifying a customer’s mobile number, provide same number and OnePipe will forward to underlying provider to evaluate what loan amounts (short term, instant loans) can be extended to the user as well as the estimated attendant risk. Providers are:
\nAfter verifying a customer’s mobile number, provide same number and OnePipe will forward to underlying provider to get a list of cards and accounts known with the customer on that provider’s platforms. Providers are:
\nProvide a customer’s card details and OnPipe will forward to the underlying provider to obtain the account number linked to it. Providers are:
\nProvide a customer’s bank account number and OnPipe will forward to the underlying provider to obtain metadata like name, etc. Providers are:
\nAccess to the APIs can only be via any of the OnePipe partners. Banks, gateways and payment service providers. Once granted access under their account, you will receive an invite email to set your password.
\nThe APIs are fairly RESTFUL and organized around the main services you would be interacting with. You can simply import this collection from the top right of the page into your Postman.
\nThe root url currently sits at:
\nhttps://api.onepipe.io\nAuthenticate your API calls by including your API key in the Authorization header of every request you make. You can manage your API keys from your dashboard.
\nSample Authorization Header:
\nAuthorization: Bearer {api_key}\nAlso, every request requires you to provide a unique request-ref per call. Then You'd need to add a custom header called Signature that's an MD5 hash of that request-ref and your api-secret separated by a semi-colon. ;.
Sample Signature Header:
\nSignature:MD5Hash(request_ref;client_secret)\nYour complete header for evey single call will look like:
\nContent-Type:application/json\nAuthorization:Bearer {{api_key}}\nSignature:{{MD5Hash(request_ref;client_secret)}}\nFor all requests, you'd put a JSON object in the body of your API call. All payloads have the following high level construct:
\n {\n \"request_ref\":\"0000000001\",\n \"request_type\":\"charge | airtime | bill-payment | transfer\",\n \"auth\": {\n \"type\": \"card | account | token | override\", \n \"secure\": \"YKBOxtdD8kZHqG7JO0C9TZ\"\n },\n \"transaction\": {\n \"amount\": \"10000\",\n \"transaction_ref\": \"000001\",\n \"transaction_desc\": \"Payment for services\",\n \"transaction_ref-parent\": \"000001\",\n \"customer\":{\n \"customer_ref\": \"000001\",\n \"firstname\": \"Kola\",\n \"surname\": \"Eboe\",\n \"email\": \"kolaebue@gmail.com\",\n \"mobile_no\": \"2348009871412\"\n }\n }\n }\n|Field|Type|Requirement|Description|\n|request_ref|string|compulsory|Takes unique value for every request made to OnePipe|\n|request_type|string|compulsory|This should be set to the servicetransfer_funds|\n|auth.type|string|compulsory|Depending on the source of fund. This can be set to either bank.account, card, token orwallet|\n|auth.secure|string|compulsory|This is the encrypted value of the source of fund. Depending on the auth type, this can be either bank account, card details, token or wallet details. See [details|https://onepipe.atlassian.net/wiki/spaces/KB/pages/201555991/Encryption+in+OnePipe] on how to encrypt the secure field.|\n|auth.provider|string|compulsory|This should be set to the name of the Provider|\n|auth.route_mode|string|N/A|This can be set tonull|\n|transaction.mock_mode|string|optional|This can be set to either live or inspect. If left as null, value will fall back to the state of the service set on the console.|\n|transaction.transaction_desc|string|optional|Description of your transaction|\n|transaction.transaction_ref_parent|string|optional|Takes value of a (parent) transaction reference|\n|transaction.customer.customer_ref|string|compulsory|Identifier for customer|\n|transaction.customer.firstname|string|optional|First name of customer|\n|transaction.customer.surname|string|optional|Surname of customer|\n|transaction.customer.email|string|optional|Email address of customer|\n|transaction.customer.mobile_no|string|optional|Phone number of customer|\n|transaction.amount|big int|compulsory|This is the amount (kobo) to be transferred|\n|transaction.transaction_ref|string|compulsory|Takes unique value for every transaction call to OnePipe.|\n|transaction.meta|object|optional|Json object of your arbitrary transaction parameters|\n|transaction.details|object|varies per transaction type|JSON object of transaction type specific elements|
\nFor all responses, you'd get a JSON object in the body of the response you receive. All payloads have the following high level construct:
\n {\n \"status\": \"Processing | WaitingForOTP | ProcessingOTP | Successful-Failed | OfflineValidating | OfflineValidated | OfflineNotifying | OfflineNotified\",\n \"message\": \"The transaction has been processed successully\",\n \"data\": {\n \"provider_responde_code\":\"00\",\n \"provider\": \"RAVE\",\n \"errors\": [],\n \"error\": null,\n \"charge_token\": \"Kz5Dev7BenV9HmLNB\",\n \"paymentoptions\": []\n }\n }\n00 for QuicktellerNOTE: Some API calls may have response elements that are only applicable to those API calls. You will see examples in the provided postman collection and across the documentation.
\nFor Custom Implementation of card or token Encryption, do use Triple DES Encryption Algorithm with your Client application secret key as the encryption key
\nE.g.
\nTripleDES.encrypt(\"{card.Pan};{card.Cvv};{card.Expdate};{card.Pin}\",secretKey)\nNOTE Expiry date is MMyy
\nMessageDigest md = MessageDigest.getInstance(\"md5\");\nbyte[] digestOfPassword = md.digest(key.getBytes(\"UTF-16LE\"));\n\nbyte[] keyBytes = Arrays.copyOf(digestOfPassword, 24);\n\nfor (int j = 0, k = 16; j < 8;) {\n keyBytes[k++] = keyBytes[j++];\n}\n\nSecretKey secretKey = new SecretKeySpec(keyBytes, 0, 24, \"DESede\");\n\nIvParameterSpec iv = new IvParameterSpec(new byte[8]);\nCipher cipher = Cipher.getInstance(\"DESede/CBC/PKCS5Padding\");\n\ncipher.init(Cipher.ENCRYPT_MODE, secretKey, iv);\n\nbyte[] plainTextBytes = toBeEncrypted.getBytes(\"UTF-16LE\");\nbyte[] cipherText = cipher.doFinal(plainTextBytes);\n\nString output = new String(Base64.encodeBase64(cipherText));\n\nreturn output;\nstring encryptedText = \"\";\nMD5 md5 = new MD5CryptoServiceProvider();\nTripleDES des = new TripleDESCryptoServiceProvider();\ndes.KeySize = 128;\ndes.Mode = CipherMode.CBC;\ndes.Padding = PaddingMode.PKCS7;\n\nbyte[] md5Bytes = md5.ComputeHash(Encoding.Unicode.GetBytes(key));\n\nbyte[] ivBytes = new byte[8];\n\n\ndes.Key = md5Bytes;\n\ndes.IV = ivBytes;\n\nbyte[] clearBytes = Encoding.Unicode.GetBytes(TextToEncrypt);\n\nICryptoTransform ct = des.CreateEncryptor();\nusing (MemoryStream ms = new MemoryStream())\n{\n using (CryptoStream cs = new CryptoStream(ms, des.CreateEncryptor(), CryptoStreamMode.Write))\n {\n cs.Write(clearBytes, 0, clearBytes.Length);\n cs.Close();\n }\n encryptedText = Convert.ToBase64String(ms.ToArray());\n}\n\nreturn encryptedText;\nfunction EncryptV2($encryption_key,$data)\n{\n $source = mb_convert_encoding($encryption_key, 'UTF-16LE', 'UTF-8');\n\n $key = md5($source, true);\n\n $key .= substr($key, 0, 8);\n\n // a 128 bit (16 byte) key\n // append the first 8 bytes onto the end\n\n\n //Pad for PKCS7\n $block = mcrypt_get_block_size('tripledes', 'cbc');\n $len = strlen($data);\n $padding = $block - ($len % $block);\n $data .= str_repeat(chr($padding),$padding);\n\n\n\n $iv = \"\\0\\0\\0\\0\\0\\0\\0\\0\";\n\n $encData = mcrypt_encrypt('tripledes', $key, $data, 'cbc',$iv);\n\n echo base64_encode($encData);\n}\nconst crypto = require('crypto');\n\nfunction encrypt(sharedKey, plainText) {\n const bufferedKey = Buffer.from(sharedKey, 'utf16le');\n\n const key = crypto.createHash('md5').update(bufferedKey).digest();\n const newKey = Buffer.concat([key, key.slice(0, 8)]);\n const IV = Buffer.alloc(8, '\\0');\n\n const cipher = crypto.createCipheriv('des-ede3-cbc', newKey, IV).setAutoPadding(true);\n return cipher.update(plainText, 'utf8', 'base64') + cipher.final('base64');\n}\nAll services subscribed to in your application are attached to providers that will end up fulfilling such service(s) on request. You can switch providers as you wish by managing the application from your dashboard and editing the service details. Also, for some endpoints, you can explicitly set the provider you would like to be used in the request payload. You would see examples in the documentation for the endpoints that support this.
\nAnywhere bank codes are required in the API specification (bank_code), this refers to the CBN bank codes. Details of all bank codes can be found here.
\nNow let's dive deeper into specific API calls.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Want to try it quickly?","slug":"want-to-try-it-quickly"},{"content":"The principles behind OnePipe","slug":"the-principles-behind-onepipe"},{"content":"Index of services & providers","slug":"index-of-services-providers"},{"content":"Getting access to the APIs","slug":"getting-access-to-the-apis"},{"content":"General API information","slug":"general-api-information"},{"content":"Authentication headers","slug":"authentication-headers"},{"content":"What requests would look like","slug":"what-requests-would-look-like"},{"content":"What responses would look like","slug":"what-responses-would-look-like"},{"content":"OnePipe standard status codes","slug":"onepipe-standard-status-codes"},{"content":"HTTP Status Codes","slug":"http-status-codes"},{"content":"Encryption of Secure element","slug":"encryption-of-secure-element"},{"content":"Switching providers for a service","slug":"switching-providers-for-a-service"},{"content":"Bank CBN Codes","slug":"bank-cbn-codes"},{"content":"Test cards","slug":"test-cards"}],"owner":"6358444","collectionId":"992bd16e-84dc-4ef6-8cad-7ab6bea23bba","publishedId":"S11GRKVh","public":true,"customColor":{"top-bar":"1F3946","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2019-07-04T12:23:06.000Z"},"item":[{"name":"Payments","item":[{"name":"OnePipe.js","item":[{"name":"Sample Page","id":"43341d23-06ce-4c45-8052-7c77d472cf3f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"","description":"Here's a sample.
\nYou can use this as boilerplate for your own implementation.
\nYou can see it in action here.
\n\n<!DOCTYPE html>\n<html>\n<head>\n <title></title>\n <meta charset=\"utf-8\" />\n <script src=\"https://js.onepipe.io/v1\"></script>\n</head>\n<body>\n <h1>This is a demo payment</h1>\n <p>Click the button to pay N10</p>\n <button type=\"button\" onclick=\"OnePipePay()\">Click me!</button>\n <script type=\"text/javascript\">\n function generateUniqueRef() {\n var min = 10000000000000;\n var max = 99999999999999;\n var transRef = (Math.random() * (max - min) + min);\n transRef = Math.round(transRef);\n return transRef.toString(); //var reqRef = transRef + '01';\n }\n function OnePipePay() {\n var transRef = generateUniqueRef();\n var handler = OnePipePopup.setup({\n requestData: {\n request_ref: transRef,//generate a unique number\n request_type: 'charge',\n api_key: '7d1IYiOKrm6BvEeMaTzc_bbbb45bf628b40919176ab26f74e5717',//API key from your console\n auth_provider: 'QTTransfer',\n transaction: {\n amount: 1000,\n currency: \"NGN\",\n transaction_ref: transRef,//generate a unique number\n transaction_desc: 'demo payment',\n customer: {\n customer_ref: '12345678800',//how you identify the customer\n firstname: 'Ope',\n surname: 'Adeoye',\n email: 'opeadeoye@gmail.com',\n mobile_no: '2348022454314'\n }\n },\n options:{\n close_popup: {\n card : \"onSuccess\"\n }\n }\n },\n callback: function (response) {\n \n //let's log the response\n console.log(response);\n \n // Contents of data is based on what OnePipe returns\n let message = (response.message || response.data.message),\n reference = response.reference,\n status = response.status,\n parentTransRef = response.parentTransRef,\n transRef = response.transRef,\n paymentmethod = response.paymentmethod,\n optionsTransRef = response.optionsTransRef,\n data = response.data,\n provider_response_code = data.provider_response_code,\n provider = data.provider,\n charge_status = data.charge_status;\n\n if(data.error){\n error = data.error,\n error_code = error.code,\n error_message = error.message;\n }\n\n\n //lets just see what's passed\n var feedback = '';\n feedback += \"payment method: \" + paymentmethod + \"\\n\";\n feedback += \"message: \" + message + \"\\n\";\n feedback += \"reference: \" + reference + \"\\n\";\n feedback += \"status: \" + status + \"\\n\";\n feedback += \"parentTransRef: \" + parentTransRef + \"\\n\";\n feedback += \"transRef: \" + transRef + \"\\n\";\n\n console.log(feedback);\n alert(feedback);\n },\n onClose: function () {\n alert('You cancelled the payment process');\n }\n });\n\n handler.execute();\n\n }\n </script>\n</body>\n</html>\nIf you find the REST APIs too complex, this mechanism is the fastest route to accepting payments on your website via OnePipe.
\nThe approach also lets you explicitly specify the provider you'd like to use to process your transaction. Supported providers include:
\nSee it in action here
\n<script src=\"https://js.onepipe.io/v1/\"></script> in your page.OnePipePay(). The contents of this function will look like the below:function OnePipePay(){\n var handler = OnePipePopup.setup({\n requestData : {\n request_ref: {{something unique & numeric}},\n request_type : 'charge',\n api_key: '{{your API key}}',\n auth_provider : {{PAYSTACK | RAVEPAY | QUICKTELLER}},\n transaction: {\n amount: {{amount in kobo}},\n currency: \"NGN\",\n transaction_ref: {{something unique & numeric}},\n transaction_desc: {{A description}},\n customer:{\n customer_ref: {{a customer ID if you have one}},\n firstname: {{first name}},\n surname: {{surname}},\n email: {{email address}},\n mobile_no: {{phone number in 234 format}} \n }\n },\n },\n callback: function(response){\n //response.reference, response.status, response.message, response.paymentmethod\n console.log(response);\n alert('Transaction status: ' + response.status + '. Payment method: ' + response.paymentmethod + '. Ref: ' + response.reference + '. Message: ' + response.message);\n },\n onClose: function(){\n alert('You cancelled the payment process');\n }\n });\n\n handler.execute();\n }\nrequestData, please look at the advanced endpoint $(\"#frmCheckout\").on('submit', function(e){\n e.preventDefault();\n OnePipePay();\n });\ncallback function properly to process your order. The placeholder in the code block above (and extracted below) can serve as boilerplate: callback: function(response){\n console.log(response);//do something more meaningful\n alert('Transaction status: ' + response.status + '. Payment method: ' + response.paymentmethod + '. Ref: ' + response.reference + '. Message: ' + response.message);\n }\nresponse.status then make a call to the query endpoint to validate the true status of the transactionYour callback function will be called with a response object that has the following properties:
\nThis component will be extended in future to suppport/wrap ALL API calls in OnePipe. There's a possiblity of breaking changes (which would be guarded against), but the documentation would be updated.
\n","event":[{"listen":"prerequest","script":{"id":"b2115f12-2b61-4fde-8170-6eab0b345dc8","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"025ef23b-1a79-40a0-bfb0-a81750c27e3b","type":"text/javascript","exec":[""]}}],"_postman_id":"62df2876-77c2-4d3b-bb5d-c245f13fccd9"},{"name":"Charge","item":[{"name":"Standard","event":[{"listen":"prerequest","script":{"id":"36874ac1-55e3-4e6f-b08e-6ce99e1aa6d4","exec":[""],"type":"text/javascript"}},{"listen":"test","script":{"id":"be337fe6-d33b-4b24-b9e2-1504580b3a9a","exec":[""],"type":"text/javascript"}}],"id":"c03fb298-ace3-49bb-bf7c-d54c91963f0e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api-key}}"},{"key":"Signature","type":"text","value":" {{signature}}"}],"body":{"mode":"raw","raw":"{\n \"request_ref\":\"{{request-ref}}\", \n \"request_type\":\"charge\", \n \"auth\": {\n \"type\": \"card\",\n \"secure\": \"{{secure.card}}\", \n \"auth_provider\": \"Paystack | RavePay | Quickteller\"\n },\n \"transaction\": {\n \"amount\": \"105000\", \n \"transaction_ref\": \"{{transaction-ref}}\", \n \"transaction_desc\": \"Payment for services\", \n \"transaction_ref_parent\": \"\", \n \"customer\":{\n \t\"customer_ref\": \"{{customer.id}}\",\n \t\"firstname\": \"{{customer.firstname}}\",\n \t\t\"surname\": \"{{customer.surname}}\",\n \t\"email\": \"{{customer.email}}\",\n \t\"mobile_no\": \"{{customer.mobile-no}}\"\n }\n }\n}\n\n"},"url":"{{url}}/v1/payments/advanced/charge","description":"With this you can debit a customer's card for a payment and obtain a token for future use if it works.
\n/v1/advanced/chargeWaitingForOTP. If so, prompt the user for OTP using the message field in the response you got/v1/payments/otp/v1/payments/query/[ref] to check status/v1/payments/otpresponse.message, then call /v1/payments/otp with whatever they type in.NOTE: Please see information on how to compute the Signature header here
With this, you'd expose a webhook url, that will receive a POST message from OnePipe upon a credit or debit activity on an account that you have access to.
First, you have to setup your webhook url on the OnePipe console.
\n![\"Setting](\"http://www.onepipe.io/docs/webhook.png\")
Upon receiving the message, please respond with a 200 - OK.
Here is the explanation of the fields you would receive.
\nNOTE: You will also recieve Signature header with which you can authenticate that the call came from OnePipe. Please see information on how the Signature header is computed here
With this call, customers can supply their name, phone number and BVN to open a bank account.
\n/v2/transactdata objectdata.provider is the provider that processed the account opening requestdata.provider_response is the response object from the provider(Bank) that processed the account opening requestdata.provider_response.accountReference is the account reference from the bankdata.provider_response.accountName is the name attached to the new accountdata.provider_response.currencyCode is the Currency Code of the accountdata.provider_response.customerEmail is the email attached to the new accountdata.provider_response.accountNumber is the generated account numberdata.provider_response.bankName is the name of the bank which the account was createddata.provider_response.bankCode is the CBN code of the new account created. You can see CBN Codes here.data.provider_response.status is the status of the account created either it's ACTIVE or INACTIVE.data.provider_response.createdOn the day in which the account was createdNOTE: Please see information on how to compute the Signature header here
In these instances, app developers can expose a webhook such that when activities occur against your bank account, or an account that you have access to, you will be notified immediately.
\nThere is also the potential for app developers to call an endpoint to generate an account number that has the capabilities for such notifications already profiled.
\nThis is useful for a new wave of payment approaches that businesses are starting to explore:
\nFor transactions that responded with success, it is strongly recommended that you follow up with this call to ascertain the true state.
\n/v1/payments/query/[ref]For transactions that require second factor authentication, call this endpoint to pass in the OTP that was sent to the user.
\n/v1/payments/otpThe payment related endpoints are covered here. At they moment, they include: charge, airtime, bill payment and OTP validation for all transactions that require it. Also included is an endpoint for double-checking a transaction status.
\n","event":[{"listen":"prerequest","script":{"id":"fadb2130-7fdd-476a-aee7-2ec450088e9d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"07313b5f-0530-477a-966f-6e3390d5bea5","type":"text/javascript","exec":[""]}}],"_postman_id":"00abe690-2706-4b0a-a541-fbc5fcf2bcca"},{"name":"Loan Scores","item":[{"name":"Get Score","event":[{"listen":"test","script":{"id":"da0493d9-93a3-490f-addc-8427b48ce71c","exec":[""],"type":"text/javascript"}},{"listen":"prerequest","script":{"id":"a7c8b15d-45b0-42cd-87f5-9112817d8e7e","exec":[""],"type":"text/javascript"}}],"id":"093721b8-2169-4cb6-9cee-39df8ea1e6f0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api-key}}","type":"text"},{"key":"Signature","value":"{{signature}}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"request_ref\":\"{{request-ref}}\",\n \"transaction\": {\n \"amount\": \"10000\",\n \"transaction_desc\": \"Payment for services\",\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"currency\": \"NGN\",\n \"algo_code\": \"markovstats1.0\",\n \"customer\":{\n \t\"customer_ref\": \"{{customer.mmobile-no}}\",\n \t\"firstname\": \"{{customer.firstname}}\",\n \t\t\"surname\": \"{{customer.surname}}\",\n \t\"email\": \"{{customer.email\",\n \t\"mobile_no\": \"{{customer.mobile-no}}\"\n }\n }\n}"},"url":"{{url}}/v1/loans/score","description":"With this call, you can pass in a customer's mobile number, and in return you'd get an estimated loan risk score denoting the maximum amount that may be offered to the user as a loan.
\n/v1/loans/scorescore objectscore.amount is the estimated amount that can be risked for this userscore.confidence is the percentage confidence associated with the estimate in amount. If the figure there is less than 10, multiply by 10 to make it a percentage. If the number is greated than 10, then it's a percentage confidence score.algo-code is the algorithm that was used in the estimateNOTE: Please see information on how to compute the Signature header here
With this call, you can contribute performance data to the scoring algorithms. It pushes in actual loan behaviour history of the user over time. Data is used to retrain and recaliberate the models under which this user has featured or been scored before.
\nNOTE: Please see information on how to compute the Signature header here
With this call, you can pass in a customer's mobile number, and in return you'd get an estimated loan risk score denoting the maximum amount that may be offered to the user as a loan. If the provider supports it, you can improve the underlying algorithm by submitting updates of the users loan behaviour over time.
\n/v1/loans/score/v1/loans/pushuserhistory to update the data that drives the scoringWith this call, you can pass in a customer's mobile number, and in return you'd get an array of estimated loan amounts from the provider(s).
\n/v1/loans/offersOffersDelivered or Successfuloffers array and present tthe options to your useroffers[].offerId is a unique ID for this offer as determined by the provider. Please note this down for use in subsequent accept Offer calloffers[].amountOffered is amount in kobo as applicable for this offeroffers[].interest is the interest in percent that will be charged by the provideroffers[].amountPayable is the amount the provider expects the customer to pay back on due dateoffers[].tenure is the loan tenure, in daysoffers[].expiryDate is the actual date the provider expects the loan to be paid backoffers[].currency the currency code for the loan. Only Naira (566) is supported at the momentoffers[].providerCode is a unique code for the provider. Please note this down for use in subsequent accept Offer callNOTE: Please see information on how to compute the Signature header here
This call follows a Get offers call. You'd pass in a transaction-ref and the chosen offer, and the loan request will be passed to the provider for processing.
\nYou'd also pass in the mechanism through which the user would pay back in the auth.secure element.
/v1/loans/acceptNOTE: Please see information on how to compute the Signature header here
With this call, you can pass in the reference of a former loan transaction to get it's status.
\n/v1/loans/statusSuccessful.loans array to see the active loans if anyloans[].id is a unique ID for this loanloans[].offerId is a unique ID for the offer that led to the loanloans[].custometId is a unique ID for thecustomer. Typically, phone numberloans[].providerId is the ID of the provider that appproved the loanloans[].channelId is the id of the channel when the loan occuredloans[].channelCode is the channel where the loan occuredloans[].status Pay special attention to this. Status will be Open for an active loanloans[].tenure is the duration of the loan. In daysNOTE: Please see information on how to compute the Signature header here
With this service, you can get a loan for a customer (with their phone number as primary identification) based on an estimated risk score as determined by the provider directly.
\n/v1/loans/offers/v1/loans/accept with the chosen offer and provider /v1/loans/status to ascertain the state of the loanWith this, you can check account connected to customers card details
\n/v1/lookup/cardaccountaccount ObjectNOTE: Please see information on how to compute the Signature header here
With this you can provide a phone number of a customer, and OnePipe will provide an array of cards and accounts linked to that phone number. Where available, that is.
\n/v1/lookup/cardsdata.accounts and data.cards arraysNOTE: Please see information on how to compute the Signature header here
With this you can provide a customer's account number + bank, and in return, receive KYC information on the account.
\n/v1/lookup/accountinfoaccount_info ObjectNOTE: Please see information on how to compute the Signature header here
[EXPERIMENTAL] Given the details of a card, this API will return the account & KYC info linked to it. And where possible the balance on the acccount.
\nhttps://next.api.onepipe.io/v1/lookup/cardaccountinfoaccount ObjectNOTE: Please see information on how to compute the Signature header here
OnePipe provides a set of value-added APIs to 'lookup' information on customers or payment instruments. From the ability to know the account linked to a card and it's balance, to the KYC information on an account, to cards previously known with a phone number. Etc.
\nThis segment describes these endpoints and how to use them.
\n","event":[{"listen":"prerequest","script":{"id":"2e130af5-aecf-4e9b-a0f7-1e9c4f4dfcf6","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"8e44ae04-1d78-4435-a47b-ab20543f43dc","type":"text/javascript","exec":[""]}}],"_postman_id":"35132a93-739a-47ec-8438-7d5444104008"},{"name":"BETA","item":[{"name":"Lookup","item":[{"name":"BVN Lookup","id":"826db549-6f73-4c9a-a87d-4d9d8434df06","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{api-key}}","type":"text"},{"key":"Signature","value":"{{signature}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"request_ref\": \"{{ref}}\",\n \"request_type\": \"bvn_lookup\",\n \"auth\": {\n \"type\": null,\n \"secure\": null,\n \"auth_provider\": \"SunTrust\"\n },\n \"transaction\": {\n \"amount\": null,\n \"transaction_ref\": \"{{ref}}\",\n \"transaction_desc\": \"My narration\",\n \"transaction_ref_parent\": null,\n \"customer\": {\n \"customer_ref\": \"{{customer.id}}\",\n \"firstname\": \"{{customer.firstname}}\",\n \"surname\": \"{{customer.surname}}\",\n \"email\": \"{{customer.email}}\",\n \"mobile_no\": \"{{customer.mobile-no}}\"\n },\n \"details\": {\n \"bvn\": \"{{bvn}}\",\n \"otp_validation\": false\n }\n }\n}"},"url":"{{url}}/v1/generic/transact","description":"With this, you can do KYC with the customer's bvn
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
The same endpoint is used to validate OTP for BVN Lookup.
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
With this, you can do KYC with the customer's account number
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
You can carry out KYC with the BVN lookup service.
\nThis segment describes the service endpoint and how to use it.
\n","event":[{"listen":"prerequest","script":{"id":"30049ae7-af66-4083-a39b-ebc5fbbc019b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"aa18169e-f889-4c38-a7c2-2de233275fbc","type":"text/javascript","exec":[""]}}],"_postman_id":"ad59e0a6-0d13-41a4-9966-a11a4cb88ea0"},{"name":"Prepaid","item":[{"name":"Issue Card","id":"9378a5f1-2b67-482d-9968-c5b77d8b720e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{api-key}}","type":"text"},{"key":"Signature","value":"{{signature}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"request_ref\": \"{{request-ref}}\",\n \"request_type\": \"prepaid card issue\",\n \"auth\": {\n \"type\": \"card\",\n \"secure\": null,\n \"auth_provider\": \"Verve\"\n },\n \"transaction\": {\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"Request for prepaid card\",\n \"transaction_ref_parent\": null,\n \"customer\": {\n \"customer_ref\": \"{{customer.id}}\",\n \"firstname\": \"{{customer.firstname}}\",\n \"surname\": \"{{customer.surname}}\",\n \"email\": \"{{customer.email}}\",\n \"mobile_no\": \"{{customer.mobile-no}}\"\n },\n \"details\": {\n \"name_on_card\": \"Opeyemi Olaniroko Adamu\",\n \"address_line_1\": \"23 Ebinpejo Lane\",\n \"address_line_2\": \"Idumota\",\n \"address_city\": \"Lagos\",\n \"address_state\": \"Lagos\",\n \"address_postal_code\": \"12301\",\n \"address_country_code\": \"NG\",\n \"card_currency_code\": \"NGN\",\n \"card_default_pin\": \"1234\"\n },\n \"meta\": {\n \"key1\": \"value\",\n \"key2\": \"value\",\n \"key3\": \"value\"\n }\n }\n}"},"url":"{{url}}/v1/generic/transact","description":"With this, you can issue prepaid cards to your customers.
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
With this, you can fund prepaid cards.
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
With this, you can check balance of a prepaid card.
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
With this, you can reset/re-issue PIN of a prepaid card.
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
With this, you can change PIN of a prepaid card.
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
Need to hold deposits from your customers in a regulatory compliant way? Prepaid cards APIs available. You can issue prepaid cards, fund cards, check balance, reset PIN and change PIN of issued cards.
\nThis segment describes these endpoints and how to use them.
\n","event":[{"listen":"prerequest","script":{"id":"30049ae7-af66-4083-a39b-ebc5fbbc019b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"aa18169e-f889-4c38-a7c2-2de233275fbc","type":"text/javascript","exec":[""]}}],"_postman_id":"e268fb21-8774-4863-a760-13b20844b89d"},{"name":"Disbursement","item":[{"name":"Funds Transfer","id":"8f666fb5-47e6-412c-87a9-170d8e759e2e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{api-key}}","type":"text"},{"key":"Signature","value":"{{signature}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":""},"url":"{{url}}/v1/generic/transact","description":"With this, you can transfer funds from your client bank account to other bank accounts.
\n/v1/generic/transactprovider_response ObjectIf status is WaitingForOTP, it means this transaction requires an OTP validation leg, and an OTP has been sent to the phone number attached to your app.
NOTE: Note that this is a one-time call.
\nNOTE: Please see information on how to compute the Signature header here
Use this endpoint to query a funds transfer/disbursement transaction.
\n/v1/generic/transact/queryprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
The same endpoint is used to validate OTP for Funds Transfer
\n/v1/generic/transactprovider_response ObjectNOTE: Please see information on how to compute the Signature header here
Need to carry out funds transfer? Transfer API is available. You can transfer funds from your client bank account to other bank accounts (Intra & Inter).
\nThis segment describes these endpoint and how to use it.
\n","event":[{"listen":"prerequest","script":{"id":"30049ae7-af66-4083-a39b-ebc5fbbc019b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"aa18169e-f889-4c38-a7c2-2de233275fbc","type":"text/javascript","exec":[""]}}],"_postman_id":"0acddb51-6493-4890-b731-82e8eeb3f7b9"}],"id":"4ac2f637-61cc-439b-ab29-b5d023838378","_postman_id":"4ac2f637-61cc-439b-ab29-b5d023838378","description":""},{"name":"UPCOMING...","item":[{"name":"Airtime","item":[{"name":"Airtime","event":[{"listen":"test","script":{"id":"e09749b2-48b8-4b51-880f-f64b96ac5a16","exec":[""],"type":"text/javascript"}},{"listen":"prerequest","script":{"id":"0e933407-8e33-4e51-a264-8028d51157f9","exec":[""],"type":"text/javascript"}}],"id":"c400f80d-ec61-44d3-bc85-eb481a3d6a26","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Bearer {{api-key}}"},{"key":"Signature","type":"text","value":" {{signature}}"}],"body":{"mode":"raw","raw":"{\n \"request_ref\":\"{{request-ref}}\",\n \"request_type\":\"airtime\",\n \"auth\": {\n \"type\": \"card\",\n \"secure\": \"{{secure.card}}\"\n },\n \"transaction\": {\n \"amount\": \"13500\",\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"Airtime test\",\n \"transaction_ref_parent\": \"\",\n \"customer\":{\n \t\"customer_ref\": \"{{customer.mobile-no}}\",\n \t\"firstname\": \"{{customer.firstname}}\",\n \t\t\"surname\": \"{{customer.surname}}\",\n \t\"email\": \"{{customer.email}}\",\n \t\"mobile_no\": \"{{customer.mobile-no}}\"\n }\n }\n}"},"url":"{{url}}/v1/payments/basic","description":"With this you can debit a customer's card and top up a provided number with airtime.
\n/v1/payments/basicWaitingForOTP. If so, prompt the user for OTP using the message field in the response you got/v1/payments/otp/v1/payments/query/[ref] to check status/v1/payments/otpThe Telco would be inferred from the mobile number. Needless to say, this would make airtime transactions for ported numbers fail. In future, we'd provide the ability to explicitly specify the Telco via a transaction.payment_code value.
NOTE: Please see information on how to compute the Signature header here
With this you can debit a customer's card and pay a bill on their behalf
\n/v1/payments/basicWaitingForOTP. If so, prompt the user for OTP using the message field in the response you got/v1/payments/otp/v1/payments/query/[ref] to check status/v1/payments/otpNOTE: Please see information on how to compute the Signature header here
Please look at the options endpoint and the advanced endpoint.
\nfollow_up_reminders array to signify a sequence of reminders to nudge the customer to complete a payment if they haven't by a set timeframe. Before executing those reminders, OnePipe will call this endpoint first.Below is the structure of the payload you should expect and how to respond.
\nPlease note that the header will contain an MD5Hash of the transaction reference and your client secret separated by a semi colon. Use this to validate that the request is from OnePipe
\nSignature Header: Signature: MD5Hash(transaction-ref;client-secret)
Please respond like below
\n\n{\n \"status\": \"Successful\",\n \"message\": \"The transaction is awaiting payment\",\n \"transaction\": {\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"Payment for services\",\n \"amount\":20000,\n \"status\": \"WaitingForOTP\",\n \"follow_up\":\"true\",\n \"customer\": {\n \"customer_ref\": \"{{customer.id}}\",\n \"firstname\": \"{{customer.firstname}}\",\n \"surname\": \"{{customer.surname}}\",\n \"email\": \"{{customer.email}}\",\n \"mobile_no\": \"{{customer.mobile-no}}\"\n }\n }\n}\n\nPlease look at the options endpoint and the advanced endpoint.
\nBelow is the structure of the payload you should expect and how to respond.
\nPlease note that the header will contain an MD5Hash of the transaction reference and your client secret separated by a semi colon. Use this to validate that the request is from OnePipe
\nSignature Header: Signature: MD5Hash(transaction-ref;client-secret)
Please respond like below
\n{\n \"status\": \"Successful\",\n \"message\": \"A message signifying payment received.\"\n}\nPlease look at the options endpoint and the advanced endpoint.
\nfollow-up-reminders array to signify a sequence of reminders to nudge the customer to complete a payment if they haven't by a set timeframe. After executing a reminders, OnePipe will call this endpoint to let you know the status.Below is the structure of the payload you should expect and how to respond.
\nPlease note that the header will contain an MD5Hash of the transaction reference and your client secret separated by a semi colon. Use this to validate that the request is from OnePipe
\nSignature Header: Signature: MD5Hash(transaction-ref;client-secret)
Please respond like below\nBasically, just acknowledge receipt
\n{\n \"status\": \"successful\",\n \"message\": \"Ack.\"\n}\nThe general concept is: Don't lose the sale. The objective is to be able to fulfill the transactions both online and offline; or generallly speaking: 'later'.
\nPayment failover
\nPayment follow ups
\nHere's how it works
\nYou can call this endpoint with a particular transaction's details, and OnePipe will respond with an array of possible options with which the customer can fulfill the payment afterwards..
\nThe options availble at the moment include
\nWe are constantly looking for more possible payment options, therefore this list will be a growing one. As it increases, the documentation will be updated.
\nOn calling this endpoint, the customer would receive a text message with instructions to view the available options. You'd also get back an array of the supported options.
\nYou can also include a follow_up_reminders array to signify a sequence of reminders to nudge the customer to complete a payment if they haven't by a set timeframe.
/v1/payments/options/chargedata.paymentoptions array.NOTE: Please see information on how to compute the Signature header here
With this endpoint, you can debit a customer's card for a payment and obtain a token for future use if successful. You can also embed an options object to take advatage of the failover & follow-up mechanisms available with OnePipe. Please take a look at Advanced - options. This endpoint basically combines that with a Basic - charge.
The endpoint also lets you explicitly specify the provider you'd like to use to process your transaction. Supported providers include:
\nIf you don't specify one, it would default to the provider you have configured on your console.
\n/v1/payments/advanced/chargeWaitingForOTP. If so, prompt the user for OTP using the message field in the response you got/v1/payments/otp/v1/payments/query/[ref] to check statusdata.paymentoptions array in the response. To see what you can do with this, please look at the options endpoint/v1/payments/otpNOTE: Please see information on how to compute the Signature header here