At Fidelity, payment processing and classic banking, we remain committed to a collaborative effort to expand the opportunities that financial services represent and deepen financial inclusion.
\nThe bouquet of APIs on Paygate Plus helps to further this objective.
\nTo get started, sign up for Paygate Plus by visiting https://paygateplus.ng. Once your account has been approved, you will receive an invite email to set your password on the platform.
\nSet up your password
\nLogin with newly set password
\nGo to My Settings
\nGO to API Settings
\nGenerate your API key and secret
\nClick Save Changes to save the newly generated API credentials
\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 base url currently sits at:
\nhttps://api.paygateplus.ng\n\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.
\nOnline Encryption Tool:
https://onepipe.io/tools/encryptor/Home/Encrypt
Sample Authorization Header:
\nAuthorization: Bearer {api_key}\n\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)\n\nYour complete header for evey single call will look like:
\nContent-Type:application/json\nAuthorization:Bearer 93qb3RbJgRfZDb9BcmzG_cbcc214131d646b7adb7206f8589a878\nSignature:{{MD5Hash(request_ref;client_secret)}}\n\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\":\"collect | disburse |etc\",\n \"auth\": {\n \"type\": \"bvn | bank.account\", \n \"secure\": \"YKBOxtdD8kZHqG7JO0C9TZ\",\n \"auth_provider\": \"Fidelity\"\n },\n \"transaction\": {\n \"amount\": 10000,\n \"transaction_ref\": \"000001\",\n \"transaction_desc\": \"A random transaction\",\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 \"meta\":{\n \"a_key\":\"a_meta_value_1\",\n \"b_key\":\"a_meta_value_2\"\n },\n \"details\": {\n \"key\": 'value'\n }\n }\n }\n\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\": \"Fidelity\",\n \"errors\": [],\n \"error\": null,\n \"charge_token\": \"Kz5Dev7BenV9HmLNB\",\n \"paymentoptions\": []\n }\n }\n\nstatus: Indicates the state of the request, whether successful, failed or anything in between
\nmessage: Provides a text description of the state of the request and at times a message for the customer
\ndata: Will contain much more details of the outcome of the request. The values within this could vary by request type or endpoint called but some standard elements would be in almost all calls
\nprovider_response_code: The actual response code received from the underlying provider, e.g. 00 for Quickteller
provider: The provider that was used to process the request
\nerrors: In case of a failed transaction, this contains the lists of errors that occurred while processing the transaction
\nerror: This contain the most important error that hinders the successful completion of the transaction.
We highly recommend that developers use the Errors field to determine the result of an API call. As an empty Errors node indicate a successful transaction.
NOTE: 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.
\nSuccessful: For all requests that were successfully processed
\nFailed: If a request fails. Read the errors object(s)
\nWaitingForOTP: If a request requires OTP validation for completion.
\nPendingValidation: If a request requires other information to be supplied for completion.
\nProcessing: If a transaction request is still in a processing state and needs to be subsequently queried.
\nOptionsDelivered: Applicable only for services that support some form of options processing.
\nInvalidID: If an ID being looked up by service is not valid.
\nFraud: If a request is flagged as suspicious.
\nDuplicate: If a similar request has been made earlier within a stipulated time frame of 5 minutes.
\n[Anything else]: This would vary per endpoint called. Applicable values would be in the documentation for that endpoint.
\n200: A successful request occurred, do note that the description field on the response can contain further steps to be carried on this transaction
\n400: Data validation error occurred due to inconsistent data supplied by the client
\n401: Invalid request authorization, which might be due to invalid API key or the client is not registered for the service being accessed.
\n500: An internal server error at our End, this should be reported if it persists.
\nFor encryption of values for the auth.secure field, you'd use Triple DES Encryption algorithm with your application secret key as the encryption key
E.g.
\nTripleDES.encrypt(\"{bvn}\",secretKey)\nTripleDES.encrypt(\"{bank_account;bank_code}\",secretKey)\nTripleDES.encrypt(\"{otp}\",secretKey)\n\nNOTE For DCIR:
\nCVV is not required for Card-Present transactions, the cvv position should be left empty.
\nTripleDES.encrypt(\"{card.Pan;card.Cvv;card.Expdate;card.Pin}\",secretKey) => Card-Not-Present\nTripleDES.encrypt(\"{card.Pan;;card.Expdate;card.Pinblock}\",secretKey) => Card-Present\n\nNOTE Expiry date is YYMM
\nMessageDigest md = MessageDigest.getInstance(\"md5\");\nbyte[] digestOfPassword = md.digest(key.getBytes(\"UTF-16LE\"));\nbyte[] keyBytes = Arrays.copyOf(digestOfPassword, 24);\nfor (int j = 0, k = 16; j < 8;) {\n keyBytes[k++] = keyBytes[j++];\n}\nSecretKey secretKey = new SecretKeySpec(keyBytes, 0, 24, \"DESede\");\nIvParameterSpec iv = new IvParameterSpec(new byte[8]);\nCipher cipher = Cipher.getInstance(\"DESede/CBC/PKCS5Padding\");\ncipher.init(Cipher.ENCRYPT_MODE, secretKey, iv);\nbyte[] plainTextBytes = toBeEncrypted.getBytes(\"UTF-16LE\");\nbyte[] cipherText = cipher.doFinal(plainTextBytes);\nString output = new String(Base64.encodeBase64(cipherText));\nreturn output;\n\nstring encryptedText = \"\";\nMD5 md5 = new MD5CryptoServiceProvider();\nTripleDES des = new TripleDESCryptoServiceProvider();\ndes.KeySize = 128;\ndes.Mode = CipherMode.CBC;\ndes.Padding = PaddingMode.PKCS7;\nbyte[] md5Bytes = md5.ComputeHash(Encoding.Unicode.GetBytes(key));\nbyte[] ivBytes = new byte[8];\ndes.Key = md5Bytes;\ndes.IV = ivBytes;\nbyte[] clearBytes = Encoding.Unicode.GetBytes(TextToEncrypt);\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}\nreturn encryptedText;\n\nfunction EncryptV2($encryption_key, $data)\n{\n $method = \"des-ede3-cbc\";\n $source = mb_convert_encoding($encryption_key, 'UTF-16LE', 'UTF-8');\n $encryption_key = md5($source, true);\n $encryption_key .= substr($encryption_key, 0, 16);\n $iv = \"\\0\\0\\0\\0\\0\\0\\0\\0\";\n $encData = openssl_encrypt($data, $method, $encryption_key, $options = OPENSSL_RAW_DATA, $iv);\n return base64_encode($encData);\n};\n\nconst crypto = require('crypto');\nfunction encrypt(sharedKey, plainText) {\n const bufferedKey = Buffer.from(sharedKey, 'utf16le');\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 const cipher = crypto.createCipheriv('des-ede3-cbc', newKey, IV).setAutoPadding(true);\n return cipher.update(plainText, 'utf8', 'base64') + cipher.final('base64');\n}\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":"Build on reliable banking infrastructure","slug":"build-on-reliable-banking-infrastructure"},{"content":"Want to try it quickly?","slug":"want-to-try-it-quickly"},{"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":"Standard status codes","slug":"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"}],"owner":"6358444","collectionId":"ec7e062e-ee83-4f44-9214-2a2f6222e4b4","publishedId":"UUy7ZPGS","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"0E247D","highlight":"78b943"},"publishDate":"2021-10-07T14:06:28.000Z"},"item":[{"name":"Payments","item":[{"name":"Online payments","item":[{"name":"Send Invoice","event":[{"listen":"test","script":{"id":"f9da3641-eebb-4e93-b0b0-e115afab8fab","exec":[""],"type":"text/javascript","packages":{}}},{"listen":"prerequest","script":{"id":"83395107-f37c-496e-8fb4-607164a2db67","exec":[""],"type":"text/javascript","packages":{}}}],"id":"3c1bcd21-6788-4f4d-99cd-d0d190893ae6","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":"F5CB3C9028B8CAE185B6B892DEFE0995"}],"body":{"mode":"raw","raw":"{\n \"request_ref\": \"{{request-ref}}\",\n \"request_type\": \"send_invoice\",\n \"auth\": {\n \"type\": null,\n \"secure\": null,\n \"auth_provider\": \"PayGatePlusCardService\",\n \"route_mode\": null\n },\n \"transaction\": {\n \"mock_mode\": \"Live\",\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"A random transaction\",\n \"transaction_ref_parent\": \"\",\n \"amount\": 10000,\n \"customer\": {\n \"customer_ref\": \"{{customer_id}}\",\n \"firstname\": \"Uju\",\n \"surname\": \"Usmanu\",\n \"email\": \"ujuusmanu@gmail.com\",\n \"mobile_no\": \"234802343132\"\n },\n \"meta\": {\n \"send_email\": true,\n \"currency\": \"GBP\"\n },\n \"details\": {\n \"page_slug\": \"card\"\n }\n }\n}"},"url":"https://api.paygateplus.ng/v2/transact","description":"With this service, the calling app can request for payment to be made by a customer. Paygate Plus aggregates multiple payment providers together into one integration and offers you a single unified workflow for your integration.
\nThe operational sequence is below:
\nsend invoice call to the endpoint providedpost code or date of birth) and after confirmation they'd see an array of supported payment methods in the specified currency. They'd complete the payment.query call to the provided endpoint to double confirm. Documentation here. Remember to use the transaction.transaction_ref element of the original send invoice call.Here's an example of what a customer will experience.
\nNOTE 1: Amount to be processed should be in lower denomination.
NOTE 2: Please remember to include the transaction.meta.currency element
Please see information on how to compute the Signature header here.
For information on how to encrypt auth.secure value, see here.
If you find the REST APIs too complex, or the user experience for the send invoice approach doesn't suit your needs, then this mechanism with an inline javascript embed is the fastest route to accepting payments on your website .
\nSee it in action here
\n1. Include in your page. Preferably in the head section
<script src=\"https://js.paygateplus.ng/v2\"></script>\n\n2. At the point of payment, attach a javascript function to your Pay button. Let's assume this function is called OnePipePay()
<button type=\"button\" onclick=\"OnePipePay()\">Pay!</button>\n\n3. Then define the function and what it does.
\n<script type=\"text/javascript\">\n //This is just a temporary unique ref generator. Please use yours to tie to the initiated transaction\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 //generate a unique reference for your transaction\n var transRef = generateUniqueRef();\n //setup the payment\n var handler = OnePipePopup.setup({\n requestData: {\n //set the unique reference\n request_ref: transRef,\n //set the request type to 'collect'\n request_type: 'collect',\n //set your API key\n api_key: 'XnxMycu54c0tbRwS9ejS_37d8425664e943718fe5b43f109852cd', \n //set auth to null\n auth: null,\n //provide the transaction details\n transaction: {\n //set test or live (supported values are Live|Inspect)\n mock_mode: document.getElementById('mode').value,\n //set the amount in lower denomination\n amount: document.getElementById('amt').value * 100,\n //set the currency (GBP|NGN\\USD|EUR)\n currency: document.getElementById('currency').value,\n //set the unique ref\n transaction_ref: transRef,//generate a unique number\n //set a description \n transaction_desc: 'demo payment',\n //set the customer details\n customer: {\n customer_ref: 'Agent_007',//how you identify the customer\n firstname: 'James',\n surname: 'Bond',\n email: 'james@mi5.com',\n mobile_no: '08022454314'\n },\n meta: {\n //set the currency\n currency: document.getElementById('currency').value\n },\n details:null,\n /*options: {\n default_view : {\n option : 'voucher',\n provider: 'mtn',\n },\n }*/\n },\n },\n /****Now handle the post-payment callback ******/\n callback: function (response) {\n //let's log the response\n console.log(JSON.stringify(response));\n console.log(response);\n // read all the contents from the response\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 if(data.error){\n error = data.error,\n error_code = error.code,\n error_message = error.message;\n }\n //lets just see what's passed --> Ideally, you'd complete the payment and process the order\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 console.log(feedback);\n alert(feedback);\n },\n //handle for cases where the customer closes the payment modal\n onClose: function () {\n alert('You cancelled the payment process');\n }\n });\n //Execute the entire routine above\n handler.execute();\n }\n </script>\n\n4. Within your callback, read the value of response.status then make a server side call to the query endpoint to validate the true status of the transaction
Your callback function will be called with a response object that has the following properties:
\n","urlObject":{"query":[],"variable":[]}},"response":[{"id":"c7e472d6-a1ef-4eab-b89b-7c93c0b4aa89","name":"Sample Page","originalRequest":{"method":"GET","header":[],"url":""},"_postman_previewlanguage":"html","header":null,"cookie":[],"responseTime":null,"body":"\n\n\n\n\n\nPayment amount:
\n\n\n\n\n\n\nTwo possible ways to integrate payments into your website or checkout experience
\nPaygatePlus.js: Lets you invoke the payment modal directly on your web pages. After they complete their payment, you'd receive a response object to your JS function invocation
\nSend invoice REST API: Returns to you a payment link to which you can simply redirect your customers. When they complete their payment, you'd recieve am event on your webhook URL
\nSee the details of both approaches below.
\n","event":[{"listen":"prerequest","script":{"id":"f50a2583-c5e1-426a-9ef2-19e031b35397","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"275c9c4f-87f2-4606-acbf-2c07ad1f2c81","type":"text/javascript","exec":[""]}}],"_postman_id":"9764e134-a683-4413-9791-ee095a888359"},{"name":"PaywithTransfer","item":[{"name":"PWA","item":[{"name":"1. Request payment - single - PWT","id":"9069429d-4b29-4f87-b752-bdcce65f18a2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {{api-key}}","type":"text"},{"key":"Signature","value":"F5CB3C9028B8CAE185B6B892DEFE0995","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"request_ref\": \"{{request-ref}}\",\n \"request_type\": \"send invoice\",\n \"auth\": {\n \"type\": null,\n \"secure\": null,\n \"auth_provider\": \"PaywithAccount\"\n },\n \"transaction\": {\n \"mock_mode\": \"Inspect\",\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"collect a payment\",\n \"transaction_ref_parent\": null,\n \"amount\": 12200,\n \"customer\": {\n \"customer_ref\": \"{{customer_ref}}\",\n \"firstname\": \"{{customer_firstname}}\",\n \"surname\": \"{{customer_surname}}\",\n \"email\": \"{{customer_email}}\",\n \"mobile_no\": \"{{customer_mobile_no}}\"\n },\n \"meta\": {\n \"type\":\"single_payment\",\n \"expires_in\": 30, //minutes\n \"skip_messaging\": false,\n \"biller_code\" : \"{{biller_code}}\"\n },\n \"details\": {}\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paygateplus.ng/v2/transact","description":"Send Invoice PWT
\nThe Send Invoice service generates a virtual account for a single payment collection. This account can then be shared with the customer for settlement.
\nThe type and secure fields in the auth object are set to null since this service allows transfers from any bank.
Other customer fields (firstname, surname) are optional for this service. They may be provided, but can also be left as empty strings (\"\")
The meta.type field must be \"single_payment\", which indicates this is a one-time virtual account.
An expires_in value must be specified (in minutes) to determine how long the virtual account remains active.
The skip_messaging field is a boolean that controls whether the system sends payment details to the customer via WhatsApp, email, or SMS:
false → Notifications will be sent.
true → No notifications will be sent.
Send Invoice PWT
\nThe Send Invoice service generates a virtual account for a single payment collection. This account can then be shared with the customer for settlement.
\nThe type and secure fields in the auth object are set to null since this service allows transfers from any bank.
Other customer fields (firstname, surname) are optional for this service. They may be provided, but can also be left as empty strings (\"\")
The meta.type field must be \"single_payment\", which indicates this is a one-time virtual account.
An expires_in value must be specified (in minutes) to determine how long the virtual account remains active.
The skip_messaging field is a boolean that controls whether the system sends payment details to the customer via WhatsApp, email, or SMS:
false → Notifications will be sent.
true → No notifications will be sent.
Send Invoice PWA
\nThis service is used when you want to collect a single payment directly from a specific customer bank account. , this flow is restricted: the payment must come from the exact account provided in the secure field.
Auth Object
\ntype → \"bank.account\" because you are binding this payment to a specific bank account.
secure → contains the encrypted account details (e.g., {account_number};{cbn_bankcode} encrypted with TripleDES and your secret key).
auth_provider → \"PaywithAccount\".
Why type and secure have values here
In this service, the customer is required to pay only from the specified account.
\nFor example, if the secure field holds a Zenith Bank account, then the transfer must originate from that Zenith account.
\nIf the customer pays from another account, the transaction will be disputed because it violates the mandate of this request.
\nTransaction Object
\namount → mandatory, since this is a single payment collection.
firstname and surname → optional; they can be provided or left as empty strings.
customer_ref → must still be the 13-digit phone number starting with 234.
Meta Object
\nAn expires_in value must be specified (in minutes) to determine how long the virtual account remains active.
The skip_messaging field is a boolean that controls whether the system sends payment details to the customer via WhatsApp, email, or SMS:
false → Notifications will be sent.
true → No notifications will be sent.
Collect (Direct Debit)
\nThis service is used to initiate a single payment debit from a customer’s bank account. this method requires the payer’s account details to be explicitly provided.
For this request to succeed, the customer must already have an active mandate on their account. In other words, their account must have been tokenized beforehand. Without a valid mandate, the debit attempt will fail.
Auth Object
\ntype: \"bank.account\" → specifies that the debit is being done on a bank account.
secure: contains the encrypted token (linked to the customer’s account) that was created when the mandate was set up. This token is what authorizes the debit.
\nauth_provider: \"PaywithAccount\".
Amount: the amount to be debited from the customer’s account.
\nMeta Object
\nbiller_code → identifies the biller on whose behalf the debit is being made.
\nThis request is not an instruction for the customer to initiate payment. Instead, the debit is initiated directly on the customer’s tokenized account.
\nThe secure field is critical, as it ensures the debit is tied to the correct customer mandate.
\nSend Invoice (Installment Payment)
\ntype: \"bank.account\" → specifies that the payment is tied to a specific customer bank account.
secure: contains the encrypted account details (e.g., {account_number};{cbn_bankcode} encrypted with TripleDES and your secret key)
auth_provider: \"PaywithAccount\".
Transaction Object
\namount: the total amount to be collected across the instalments. Must be in kobo (e.g., 30000 = ₦300).
transaction_ref: unique reference for this collection.
\ntransaction_desc: description of the payment (free text).
\ncustomer_ref: the 13-digit customer phone number starting with 234.
firstname, surname, email, mobile_no → optional; they can be populated or left as empty strings.
\ntype: \"instalment\" → instructs the system this is an instalment-based payment.
down_payment: upfront amount to be collected immediately (in kobo).
\nrepeat_frequency: how often subsequent payments occur (daily, weekly, monthly).
repeat_start_date: the date and time when instalment deductions begin. Must follow the format: yyyy-MM-dd-hh-mm-ss.
number_of_payments: total number of instalment payments (excluding the down payment).
\nbiller_code: mandatory; identifies the biller on whose behalf the collection is being made.
\nWhen this request is made, the API responds with a virtual account where the customer must pay the down payment.
\nThe transfer for the down payment must come from the same bank account linked in the secure field. If payment is made from another account, it will be disputed.
Once the down payment is settled, all subsequent instalments are debited automatically from the customer’s mandate-linked account, based on the schedule (repeat_frequency and repeat_start_date).
Send Invoice (subscription payment)
\ntype: \"bank.account\" → ties the subscription to a specific customer bank account.
secure: contains the encrypted account details (e.g., {account_number};{cbn_bankcode} encrypted with TripleDES and your secret key)
auth_provider: \"PaywithAccount\".
amount: the recurring amount to be debited at each cycle. Must be in kobo (e.g., 10500 = ₦105).
transaction_ref: unique reference for this subscription request.
\ntransaction_desc: description of the subscription (free text).
\ncustomer_ref: must always be the 13-digit phone number starting with 234.
firstname, surname, email, mobile_no: optional; they can be populated or left as empty strings.
\nDefines the subscription plan:
\ntype: \"subscription\" indicates this request is setting up a recurring debit.
repeat_frequency: how often the debit should occur (daily, weekly, monthly).
repeat_start_date: the date and time when the subscription debits should begin. Format: yyyy-MM-dd-hh-mm-ss.
repeat_end_date: the date and time when the subscription should automatically stop. Format: yyyy-MM-dd-hh-mm-ss.
biller_code: mandatory; identifies the biller on whose behalf the subscription is being set up.
\nSubscription Flow
\nRequest Initiation
\nWhen you send a subscription request, the response you receive depends on the activation method agreed with the business (either first payment or transfer).
\nThis first action serves as customer consent to allow recurring debits on their account.
\nFirst Payment (Virtual Account Route)
\nEvery time a new subscription is initiated, a virtual account is generated.
\nThe customer is required to make a transfer to this account for the first billing cycle (e.g., paying for the first month of a subscription).
\nOnce this payment is received, the subscription becomes active.
\nSubsequent debits will then occur automatically from the customer’s linked account, according to the start date, end date, and repeat frequency defined in the request.
\nTransfer (Activation URL Route)
\nAlternatively, the response will include an activation_url.
You can either:
\nDisplay the content of the URL directly in your own platform (skipping external messaging), or
\nSend the URL to the customer via SMS, WhatsApp, or any other channel.
\nThe customer follows the instructions and gives consent by sending a transfer (via NIBSS).
\nOnce the transfer is completed and confirmed, the subscription is activated.
\nFuture recurring debits then proceed automatically from the authorized account.
\nSubsequent Debits
\nAfter activation (via first payment or transfer), the system handles debits automatically:
\nBased on the repeat_frequency (daily, weekly, monthly, etc.).
Continuing until the repeat_end_date or when the subscription is cancelled.
Check Active Mandate On An Account(Get Account Max)
\nThis service allows you to verify if a customer already has an active mandate on a specific account. The account details are the same ones encrypted into the secure field of the auth object.
type: \"bank.account\" → indicates the mandate check is being done against a bank account.
secure: encrypted account details (token or account identifier tied to mandate).
auth_provider: \"PaywithAccount\".
amount: 0 → since this is only a mandate verification, no debit occurs.
Here are the preliminary steps before you can use the APIs
\nSign up on PaywithAccount [guide]
\nRequest API access [guide]
\nOnce approved, you will receive 2 emails:
\nThat contains the postman collection
\nAnother with a link to set up your password. After setting your password, log in and retrieve your credentials.
\nAll requests to the API are made through a single base URL:
\nhttps://api.paygateplus.ng\n\nThere are no separate URLs for sandbox and production. Instead, the environment is controlled by the mock_mode field in the request payload.
mock_mode = inspect → Sandbox Mode
Requests are processed in test mode.
\nYou receive mock responses that simulate the expected behavior of the endpoint.
\nRecommended for development and early-stage integration testing.
\nmock_mode = live → Production Mode
Requests are processed in live mode.
\nYou receive real-time responses based on actual inputs and live transaction flows.
\nUse this mode only after successful sandbox testing.
\nDuring the integration phase, you will be provided with limited access to the mock_mode = live setting.
This allows you to preview real-time responses and perform end-to-end testing of your workflows.
\nAccess is controlled and monitored to ensure stability and compliance.
\nFull unrestricted access to production (mockmode = live) is granted only after your integration is fully tested and approved.
Every API call must include specific headers for authentication, security, and proper request handling. Below is a breakdown of the required headers and their purposes:
\nContent-Type: application/json\n\nInforms the server that the body of the request is in JSON format
\nRequired for all request
\n2. Authorization
\nAuthorization: Bearer {api_key}\n\nThis header contains the API key assign to you
\nIt authenticates the request and confirms that the call is made by an authorized client
\nFormat: Bearer {{your_api_key}}
3. Signature
Signature: {{MD5Hash(request_ref;client_secret)}}\n\nEnsures integrity and security of the request.
\nGenerated using an MD5 hash function
\nTo compute the signature:
\nConcatenate the request_ref (a unique reference for every API call) and your client_secret separated by a semi colon (;).
Apply the MD5 hashing function to the concatenated string.
\nThis hashed value is then sent as the Signature header.
Purpose:
\nTo verify that the request originates from a trusted source.
\nServes as a second layer of security by “signing” the request.
\nExample Header format
Your complete header for evey single call will look like
Content-Type:application/json\nAuthorization:Bearer 93qb3RbJgRfZDb9BcmzG_cbcc214131d646b7adb7206f8589a878\nSignature:{{MD5Hash(request_ref;client_secret)}}\n\nrequest_ref: A unique identifier generated for every API call. No two requests should have the same reference.
\nThe server validates the Signature by regenerating the hash internally and comparing it with the one provided.
If the values do not match, the request will be rejected.
\nEvery API request uses a common payload structure. This ensures consistency across services and reduces integration effort. The payload is divided into standard objects, each serving a specific purpose.
\nThis defines the authentication type and varies depending on the service being called.
\nFor get banks service → the value is null.
For mandate creation → the value is \"bank.account\", because a mandate is being placed on a specific account.
If type has a value, then secure must also have a value.
\nTripleDES.encrypt(\"{account_number};{cbn_bankcode}\", secretKey)\n\nUsing the formula, the full object looks like this:
\n\"type\": \"bank.account\",\n\"secure\": TripleDES.encrypt(\"{account_number};{cbn_bankcode}\", secretKey),\n\"auth_provider\": \"paywithaccount\"\n\nMessageDigest md = MessageDigest.getInstance(\"md5\");\nbyte[] digestOfPassword = md.digest(key.getBytes(\"UTF-16LE\"));\nbyte[] keyBytes = Arrays.copyOf(digestOfPassword, 24);\nfor (int j = 0, k = 16; j < 8;) {\n keyBytes[k++] = keyBytes[j++];\n}\nSecretKey secretKey = new SecretKeySpec(keyBytes, 0, 24, \"DESede\");\nIvParameterSpec iv = new IvParameterSpec(new byte[8]);\nCipher cipher = Cipher.getInstance(\"DESede/CBC/PKCS5Padding\");\ncipher.init(Cipher.ENCRYPT_MODE, secretKey, iv);\nbyte[] plainTextBytes = toBeEncrypted.getBytes(\"UTF-16LE\");\nbyte[] cipherText = cipher.doFinal(plainTextBytes);\nString output = new String(Base64.encodeBase64(cipherText));\nreturn output;\n\nstring encryptedText = \"\";\nMD5 md5 = new MD5CryptoServiceProvider();\nTripleDES des = new TripleDESCryptoServiceProvider();\ndes.KeySize = 128;\ndes.Mode = CipherMode.CBC;\ndes.Padding = PaddingMode.PKCS7;\nbyte[] md5Bytes = md5.ComputeHash(Encoding.Unicode.GetBytes(key));\nbyte[] ivBytes = new byte[8];\ndes.Key = md5Bytes;\ndes.IV = ivBytes;\nbyte[] clearBytes = Encoding.Unicode.GetBytes(TextToEncrypt);\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}\nreturn encryptedText;\n\nfunction EncryptV2($encryption_key,$data)\n{\n $source = mb_convert_encoding($encryption_key, 'UTF-16LE', 'UTF-8');\n $key = md5($source, true);\n $key .= substr($key, 0, 8);\n // a 128 bit (16 byte) key\n // append the first 8 bytes onto the end\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 $iv = \"\\0\\0\\0\\0\\0\\0\\0\\0\";\n $encData = mcrypt_encrypt('tripledes', $key, $data, 'cbc',$iv);\n echo base64_encode($encData);\n}\n\nconst crypto = require('crypto');\nfunction encrypt(sharedKey, plainText) {\n const bufferedKey = Buffer.from(sharedKey, 'utf16le');\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 const cipher = crypto.createCipheriv('des-ede3-cbc', newKey, IV).setAutoPadding(true);\n return cipher.update(plainText, 'utf8', 'base64') + cipher.final('base64');\n}\n\nCustomer Object
\nThe customer object stores information to uniquely identify and contact the customer. Fields are optional depending on the service being called. If not required, they can be left as empty strings (\"\")
The meta object is optional and can contain extra contextual information for the transaction depending on the service.
Details Object
\nThe details object can contain additional information relevant to the transaction.
It can be empty ({}) if no extra details are needed.
With this service, the calling apps can open and assign accounts to customers or transactions.
\n**NOTE: Set auth_provider to FidelityVirtual
Notifications are useful for a new wave of payment approaches that businesses are starting to explore:
\nOpen an account and map it to a customer or specific transaction
\nAsk customers to transfer to that account
\nGet notified once a credit or debit hits that account
\nProcess the service that the customer was supposed to pay for
\nMonies are \"swept\" from that account into yours after a while.
\nWith this, you'd expose a webhook url, that will receive a POST message upon a credit or debit activity on an account that you have access to.
First, you have to setup your webhook url on the App console.
\nUpon receiving the message, please respond with a 200 - OK.
Here is the explanation of the fields you would receive.
\nWith this service, the calling apps can open Optimus virtual accounts on behalf of their customers.
\n","urlObject":{"path":["v2","transact"],"host":["https://api.paygateplus.ng"],"query":[],"variable":[]}},"response":[{"id":"afc55581-24d8-4d58-add0-22caaaa3d579","name":"Successful","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"request_ref\": \"{{request-ref}}\",\n \"request_type\": \"open_account\",\n \"auth\": {\n \"type\": null,\n \"secure\": null,\n \"auth_provider\": \"FidelityVirtual\",\n \"route_mode\": null\n },\n \"transaction\": {\n \"mock_mode\": \"Live\",\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"A random transaction\",\n \"transaction_ref_parent\": null,\n \"amount\": 0,\n \"customer\": {\n \"customer_ref\": \"2348033000989\",\n \"firstname\": \"John\",\n \"surname\": \"Doe\",\n \"email\": \"john@doe.com\",\n \"mobile_no\": \"2348033000989\"\n },\n \"meta\": {},\n \"details\": {\n \"name_on_account\": \"John J. Doe\",\n \"middlename\": null,\n \"dob\": null,\n \"gender\": null,\n \"title\": null,\n \"address_line_1\": null,\n \"address_line_2\": null,\n \"city\": null,\n \"state\": null,\n \"country\": null\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paygateplus.ng/v2/transact"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"Successful\",\n \"message\": \"Transaction processed successfully\",\n \"data\": {\n \"provider_response_code\": \"0\",\n \"provider\": \"FidelityVirtual\",\n \"errors\": null,\n \"error\": null,\n \"provider_response\": {\n \"reference\": \"{{unique reference}}\",\n \"account_number\": \"4565048125\",\n \"contract_code\": null,\n \"account_reference\": \"{{unique reference}}\",\n \"account_name\": \"AppName - John J. Doe\",\n \"currency_code\": null,\n \"customer_email\": null,\n \"bank_name\": \"Fideity Bank\",\n \"bank_code\": \"070\",\n \"account_type\": null,\n \"status\": \"ACTIVE\",\n \"created_on\": \"2019-01-15 5:35:16\"\n },\n \"client_info\": null\n }\n}"}],"_postman_id":"82838dcc-98da-4498-a533-304d6995e489"},{"name":"Open Account(Virtual) - Dynamic","event":[{"listen":"test","script":{"id":"4b345820-2cd1-48d3-be65-c6eb0340a8e2","exec":[""],"type":"text/javascript","packages":{},"requests":{}}},{"listen":"prerequest","script":{"id":"0dbd484d-ce7c-42c8-a4fc-d98124018a2d","exec":[""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"056b039f-2c65-4c6a-83b4-d183e5758b8c","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":"F5CB3C9028B8CAE185B6B892DEFE0995","type":"text"}],"body":{"mode":"raw","raw":"{\n \"request_ref\": \"{{request-ref}}\",\n \"request_type\": \"open_account\",\n \"auth\": {\n \"type\": null,\n \"secure\": null,\n \"auth_provider\": \"FidelityVirtual\",\n \"route_mode\": null\n },\n \"transaction\": {\n \"mock_mode\": \"Live\",\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"A random transaction\",\n \"transaction_ref_parent\": null,\n \"amount\": 0,\n \"customer\": {\n \"customer_ref\": \"2348033000989\",\n \"firstname\": \"John\",\n \"surname\": \"Doe\",\n \"email\": \"john@doe.com\",\n \"mobile_no\": \"2348033000989\"\n },\n \"meta\": {\n \"amount\": 1000\n },\n \"details\": {\n \"name_on_account\": \"John J. Doe\",\n \"middlename\": null,\n \"dob\": null,\n \"gender\": null,\n \"title\": null,\n \"address_line_1\": null,\n \"address_line_2\": null,\n \"city\": null,\n \"state\": null,\n \"country\": null\n }\n }\n}"},"url":"https://api.paygateplus.ng/v2/transact","description":"With this service, the calling apps can open Fidelity virtual accounts on behalf of their customers.
\nFor dynamic virtual account, set expected amount in the meta field.
\n","urlObject":{"path":["v2","transact"],"host":["https://api.paygateplus.ng"],"query":[],"variable":[]}},"response":[{"id":"6dc6a860-6e8c-4225-9114-1dc540dd53b3","name":"Successful","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Bearer {{api-key}}","type":"text"},{"key":"Signature","value":"F5CB3C9028B8CAE185B6B892DEFE0995","type":"text"}],"body":{"mode":"raw","raw":"{\n \"request_ref\": \"{{request-ref}}\",\n \"request_type\": \"open_account\",\n \"auth\": {\n \"type\": null,\n \"secure\": null,\n \"auth_provider\": \"FidelityVirtual\",\n \"route_mode\": null\n },\n \"transaction\": {\n \"mock_mode\": \"Live\",\n \"transaction_ref\": \"{{transaction-ref}}\",\n \"transaction_desc\": \"A random transaction\",\n \"transaction_ref_parent\": null,\n \"amount\": 0,\n \"customer\": {\n \"customer_ref\": \"2348033000989\",\n \"firstname\": \"John\",\n \"surname\": \"Doe\",\n \"email\": \"john@doe.com\",\n \"mobile_no\": \"2348033000989\"\n },\n \"meta\": {\n \"amount\": 1000\n },\n \"details\": {\n \"name_on_account\": \"John J. Doe\",\n \"middlename\": null,\n \"dob\": null,\n \"gender\": null,\n \"title\": null,\n \"address_line_1\": null,\n \"address_line_2\": null,\n \"city\": null,\n \"state\": null,\n \"country\": null\n }\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paygateplus.ng/v2/transact"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 24 Mar 2020 13:49:51 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Content-Length","value":"873"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"Kestrel"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"Successful\",\n \"message\": \"Transaction processed successfully\",\n \"data\": {\n \"provider_response_code\": \"0\",\n \"provider\": \"FidelityVirtual\",\n \"errors\": null,\n \"error\": null,\n \"provider_response\": {\n \"reference\": \"{{unique reference}}\",\n \"account_number\": \"4565048125\",\n \"contract_code\": null,\n \"account_reference\": \"{{unique reference}}\",\n \"account_name\": \"AppName - John J. Doe\",\n \"currency_code\": null,\n \"customer_email\": null,\n \"bank_name\": \"Fidelity Bank\",\n \"bank_code\": \"070\",\n \"account_type\": null,\n \"status\": \"ACTIVE\",\n \"created_on\": \"2019-01-15 5:35:16\",\n \"meta\": {\n \"amount\": \"1000\",\n \"expires_in_minutes\": \"30\"\n }\n },\n \"client_info\": null\n }\n}"}],"_postman_id":"056b039f-2c65-4c6a-83b4-d183e5758b8c"},{"name":"Transaction Notification","id":"22a7cc50-7a3f-4f54-a8f4-1f9238bebfac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"details\": {\n \"data\": {\n \"tag\": \"FIDELITY\",\n \"amount\": \"30.00\",\n \"status\": \"00\",\n \"bankcode\": \"000017\",\n \"bankname\": null,\n \"trandate\": \"2025-09-04T11:10:02.283\",\n \"bank_code\": \"076\",\n \"craccount\": \"4566615583\",\n \"narration\": \"4566615583/John Test/Fidelity-\",\n \"sessionid\": \"000017250904111000680177831869\",\n \"channelcode\": \"9\",\n \"chargeamount\": null,\n \"craccountname\": \"John Test Doe\",\n \"originatorbvn\": null,\n \"statusmessage\": \"Success\",\n \"account_number\": \"4566615583\",\n \"beneficiarybvn\": null,\n \"nameenquiryref\": \"000017250904111001000000111001\",\n \"originatorname\": \"OLUWASEMILOORE OLUWATOMISIN AKINLO\",\n \"referencenumber\": null,\n \"paymentreference\": \"638925809997397932\",\n \"originatorcbncode\": \"035\",\n \"originatorkyclevel\": null,\n \"beneficiarykyclevel\": null,\n \"transactionlocation\": \" \",\n \"collectionaccountNumber\": \"4011389403\",\n \"originatoraccountnumber\": \"0232321799\",\n \"destinationinstitutionbankcode\": \"000007\"\n },\n \"meta\": {\n \"route\": \"listener\",\n \"narration\": \"4566615583/John Test/Fidelity-\",\n \"cr_account\": \"4566615583\",\n \"cr_account_name\": \"John Test Doe\",\n \"originator_cbn_code\": \"035\",\n \"originator_bank_name\": null,\n \"originator_account_name\": \"OLUWASEMILOORE OLUWATOMISIN AKINLO\",\n \"originator_account_number\": \"0232321799\"\n },\n \"amount\": 3000,\n \"status\": \"Successful\",\n \"provider\": \"FidelityVirtual\",\n \"customer_ref\": \"{{customer_ref}}\",\n \"customer_email\": \"{{customer_email}}\",\n \"transaction_ref\": \"{{transaction_ref}}\",\n \"customer_surname\": \"Test\",\n \"transaction_desc\": \"4566615583/John Test/Fidelity-\",\n \"transaction_type\": \"collect\",\n \"customer_firstname\": \"Test\",\n \"customer_mobile_no\": \"2348033000989\"\n },\n \"app_info\": {\n \"app_code\": \"PAYP647540\"\n },\n \"mock_mode\": \"Live\",\n \"requester\": \"FidelityVirtual\",\n \"request_ref\": \"6cfd4e8d-f6f5-492d-95ab-e795bf56e044\",\n \"request_type\": \"transaction_notification\"\n}","options":{"raw":{"language":"json"}}},"url":"","description":"Notifications are useful for a new wave of payment approaches that businesses are starting to explore:
\nOpen an account and map it to a customer or specific transaction
\nAsk customers to transfer to that account
\nGet notified once a credit or debit hits that account
\nProcess the service that the customer was supposed to pay for
\nMonies are \"swept\" from that account into yours after a while.
\nWith this, you'd expose a webhook url, that will receive a POST message upon a credit or debit activity on an account that you have access to.
First, you have to setup your webhook url on the App console.
\nUpon receiving the message, please respond with a 200 - OK.
Here is the explanation of the fields you would receive.
\nWith this service, calling applications can open and assign virtual accounts to customers, allowing them to make transfers for a specific booking transaction.
\nSimply display the value of data.provider_response.note to the customer. This field contains the summarized payment instruction for them.
If a data.provider_response.meta.payment_link is also returned as part of the response, it means customer should be redirected to the payment_link for payment to be made.
You'll be notified each time a customer completes a payment for a booking.
\nTo enable this, provide a webhook URL that will receive a POST message whenever a booking payment is made.
\nFirst, you have to setup your webhook url on the App console.
\nUpon receiving the message, please respond with a 200 - OK.
Here is the explanation of the fields you would receive.
\nUse this endpoint to query booking.
\n**NOTE: Set transaction_ref to transaction reference used to create the booking.
The primary goal of this interface is to facilitate a Pay With Transfer concept for customers booking flight on the Airline platform.
\nThis integration interface covers two perspectives:
\nCreate Booking
\nCreate Booking - Payment Notification
\nCreate Booking - Query Payment Status
\nWith this service, the calling apps can do a transfer to a destination account number from a pre-configured account of the app. If authorisation details are required by a provider, apps will have to provide this.
\nNOTE: Amount to be processed should be in kobo with decimal places.
Please see information on how to compute the Signature header here.
For information on how to encrypt auth.secure value, see here.
/v2/transact/validate as follow up call to complete transactionWith this service, the calling apps can do a transfer to a destination account number from a given source. Authorisation details (for source of funds) will always be required by the SureGate, apps will have to provide this.
\nNOTE: Amount to be processed should be in kobo with decimal places.
Please see information on how to compute the Signature header here.
For information on how to encrypt auth.secure value, see here.
/v2/transact/validate as follow up call to complete transactionWith this service, the calling app can request or initiate payment from a customer. Provide a customer’s bank card, PayGatePlus forwards to selected provider, provider debits the linked account and credits beneficiary account tied to the app.
\nNOTE: Amount to be processed should be in kobo without decimal places.
Please see information on how to compute the Signature header here.
Note that this specification covers for both Card-Present and Card-Not-Present transactions. The differentiating factor for both types of transactions is based on the construction of values in the auth.secure field.
For information on how to encrypt auth.secure value, see here.
The meta object in this Collect specification largely carries details of the card transaction. Here's an explanation of each element:
The following 2-character response codes may be returned by the API in the provider_response_code field.
With this service, the calling app can request or initiate payment from a customer. Provide a customer’s Fidelity bank account number, PayGatePlus forwards to selected Fidelity BioMandate provider, provider debits the linked account and credits beneficiary account tied to the app. This underlying provider does a BioMandate authorisation challenge on the customer, allowing the customer to create a BioMandate PIN to be used for subsequent transactions.
\nNOTE: Amount to be processed should be in kobo with decimal places.
Please see information on how to compute the Signature header here.
For information on how to encrypt auth.secure value, see here.
/v2/transact/validate as follow up call to complete transactionenrollment_url field within the meta object, in the response payload for PendingValidationenrollment_url field would always contain a url string. Merchant needs to redirect customer to this url, for customer to go complete the BioMandate capture.enrollment_url field would have a null value.With this service, the calling apps can get available balance for a given source.
\nNOTE: Amount in response is in kobo.
Please see information on how to compute the Signature header here.
For information on how to encrypt auth.secure value, see here.
/v2/transact/validate as follow up call to complete transactionWith this service, the calling apps can get statements of accounts. Apps will collect the customer reference (account number, or any unique reference) they will like to obtain information on and forward to PaygatePlus. If authorisation details are required by a provider, apps will have to provide this. PaygatePlus will in turn forward to the provider’s dedicated implementation.
\nHere's the call sequence specific to this service...
\n/transact with the right auth details if required. See hereWaitingForOTP or PendingValidation if they require OTP verification/transact/validate to supply OTP if neededSuccessful or Failed./transact/queryprovider_response Objectstatus.message and collect the input from the user, then follow with a /transact/validatestatus.message and collect the input from the user, then follow with a /transact/validateFor a list of providers that have published and implemented this service, please see
\n\nQuestion: Why do I need to specify transaction.amountwhen it's irrelevant here?
Answer: OnePipe APIs all try to follow a common standard such that all services require the same exact payload. It's the values within the payload that will then vary, service by service. In this case, just set it to 0.
Question: What is the meta object in the request and response?
Answer: Some providers at times require or return special fields not covered by the standard. If you know what some of these fields and their values are you can set them in the request meta object and read them from the response meta object. Typically though, null is perfectly fine in most cases.
With this service, the calling apps can KYC a customer's account number. This service will only return minimal KYC information.
\nNOTE: Please see information on how to compute the Signature header here.
For information on how to encrypt auth.secure value, see here.
/v2/transact/validate as follow up call to complete transactionUse this endpoint as a follow-up call for OTP validation. Specify the transaction ref of the transaction to be validated in the transaction.transaction_ref field.
Replace the value request_type with the corresponding service name.
The OTP must be encrypted with the Triple DES encryption algorithm and should be placed in the auth.secure field.
For information on how to encrypt auth.secure value, see here.
Use this endpoint for querying transactions. Specify the transaction ref of the transaction to be queried in the transaction.transaction_ref field.
Specify the service name in the request_type field.