Paylony APIs can be authenticated by using a live or test secret key which starts with either sk_live_ or sk_test_ respectively and these keys can be find on your dashboard>api credentials menu.
\nNB: In order to call our endpoints it’s necessary to pass the key as an authorization header (Bearer token) for every request.
\nNB: In order to use the Bank transfer (payout) endpoint, an encryption is required. You need to sign your payout using your Encryption Key and perform an HMAC-512 encryption after you have arranged the payload params alphabetically and pass the result of the encryption in the header as Signature.
\nAll requests to our API must be done using the web API URL below.
\nhttps://api.paylony.com/api/v1
\nThe following operation types are supported.
\nFor notifications, a webhook is shared with you so you can be notified for inward credit transactions. The webhook is to be shared both in the testing and production environment. Its request will be sent in this format.
\n{\n \"status\": \"00\",\n \"event\": “collection”,\n \"currency\": \"NGN\",\n \"amount\": \"5000\",\n “fee”: “50”,\n \"stamp_duty\":\"0\",\n \"receiving_account\": \"1010011220”,\n \"sender_account_name\": \"Tolulope Oyeniyi\",\n \"sender_account_number\": \"00012302099\",\n \"sender_bank_code\": \"999999\",\n \"sender_narration\": \"Gift bills deposit\",\n \"sessionId\": \"0000929120221226145000\",\n \"trx\": \"202212261450837964477\",\n \"reference\": \"Paylony-20221226145000\",\n \"channel\": \"bank_transfer\",\n \"type\": \"reserved_account\",\n \"domain\": \"test\",\n \"gateway\": \"vfd\",\n \"customer_email\": \"tolulope@gmail.com\",\n \"customer_reference\": \"597zgekrzd65ebh\",\n \"timestamp\": \"2023-08-15T19:45:09.000000Z\"\n}\n\n\"reference\" — This is prefixed by your wallet name followed by a random string.
\n“amount” — This is the amount sent to the wallet account.
\n“receiving_account” — This is the account number credited with the inward transfer.
\n“sender_account_number” — This is the initiator’s account number.
\n“sender_account_name” — This is the initiator’s name.
\n\"sender_narration\" – This is the narration or remark from the sender.
\n“sender_bank_code” — This is the initiator’s bank code.
\n“timestamp” — Timestamp of the transaction.
\nNB: We will send you webhook using your webhook key as Authroization (Bearer Token) and we expect a success response from you to aknowledge the recipient of the webhook. When sharing a web hook with us, security measures such as Authentication or IP whitelisting are advised to be in place.
\n\n\nIn the case of Instant settlement, you will only get settled when the webhook response simply says \"success\" as we will only trigger settlement upon receiving success as response to the webhook sent.
\n
Webhook is sent upto 10x before giving up. If your platform us not reachable or we didn't get any response after the 10th attempt, we will stop sending the webhook notification. You can resend webhook via API or from your transaction details screen in your merchant dashboard or mobile app.
\nWe also Provide a webhook for Transfers (only transfer done via API). Here is a sample payout webhook sent to your webhook url anytime the transfer status changed from pending to failed or success
\n{\n \"status\": \"00\",\n \"event\": “payout”,\n \"currency\": \"NGN\",\n \"amount\": \"5000\",\n “fee”: “50”,\n \"account_name\": \"Tolulope Oyeniyi\",\n \"account_number\": \"00012302099\",\n \"bank_code\": \"100004”,\n \"bank_name\": “Opay”,\n \"narration\": \"Gift bills deposit\",\n \"trx\": \"202212261450837964477\",\n \"reference\": \"Vfd-x-20221226145000\",\n \"sessionid\": \"0000929120221226145000\",\n \"domain\": \"test\",\n \"statusMessage\": “success”,\n \"note\": \"\",\n \"timestamp\": “2024-04-25 18:11:05”\n}\n\n{\n \"status\": \"00\",\n \"event\": “collection”,\n \"currency\": \"NGN\",\n \"amount\": \"5000\",\n “fee”: “50”,\n \"receiving_account\": \"1010011220”,\n \"sender_account_name\": \"Tolulope Oyeniyi\",\n \"sender_account_number\": \"00012302099\",\n \"sender_bank_code\": \"999999\",\n \"sender_narration\": \"Gift bills deposit\",\n \"sessionId\": \"0000929120221226145000\",\n \"trx\": \"202212261450837964477\",\n \"reference\": \"Paylony-20221226145000\",\n \"channel\": \"bank_transfer\",\n \"type\": \"reserved_account\",\n \"domain\": \"test\",\n \"gateway\": \"vfd\",\n \"customer_email\": \"tolulope@gmail.com\",\n \"customer_reference\": \"597zgekrzd65ebh\",\n \"timestamp\": \"2023-08-15T19:45:09.000000Z\"\n}\n\n{\n \"status\": \"00\",\n \"event\": “payout”,\n \"currency\": \"NGN\",\n \"amount\": \"5000\",\n “fee”: “50”,\n \"account_name\": \"Tolulope Oyeniyi\",\n \"account_number\": \"00012302099\",\n \"bank_code\": \"100004”,\n \"bank_name\": “Opay”,\n \"narration\": \"Gift bills deposit\",\n \"trx\": \"202212261450837964477\",\n \"reference\": \"Vfd-x-20221226145000\",\n \"sessionid\": \"0000929120221226145000\",\n \"domain\": \"test\",\n \"statusMessage\": “success”,\n \"note\": \"\",\n \"timestamp\": “2024-04-25 18:11:05”\n}\n\nThis API Endpoints allows you to create a reserved account by providing the required details.
\nProvide dob in either of the formats below
\n1989-10-04
\n04 October 1989
\nAvailable providers are
\nnetbank
\nsafehaven
\nprovidus
\ngtb
\nvfd
\nIt is required to parse the provider parameter for the account you want to create. When provider is not provided, any provider account would be generated as determines by our system.
\nProviding BVN or NIN determine your possible transaction limit on account created due to CBN regulations.
\nWhile BVN is Required for some providers and not in some cases. It is up to you to handle your user verification on your platform. Else, we advice you to require user bvn on your platform for future refrerence.
\nFor Safe Haven MFB: It is now required to generate BVN OTP from the BVN phone number and submit both OTP and BVN to generate safehaven account number.
\n\n\n","urlObject":{"path":["create_account"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"0d036e0a-a0b2-4bc8-9a8c-a8b96bf00c41"},{"name":"Create Checkout Virtual Account","id":"c6426572-b7cb-47be-9d27-b120d51e5690","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\":\"Giftibills Tolulope\",\n \"email\":\"toluxsys@yahoo.ca\",\n \"amount\":\"100\",\n \"currency\":\"NGN\",\n \"reference\":\"svjsvosvososeop\",\n \"phone\":\"07036218209\",\n \"title\":\"\",\n \"description\":\"\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paylony.com/api/v1/create_checkout_account","description":"To get BVN OTP, Dial *565*3# , Enter 11113 as iGree Number then Send. Finally, on Prompt, Input your BVN Number. An 8 DIGIT OTP will be sent to you. Enter submit this as otp in account create dedicated virtual account endpoint.
\n
This API Endpoints allows you to create a dynamic account by providing the required details.
\nThis is a ontime payment account that allows you to generate a virtual account for a one time payment.
\nNOTE: you can only send payment to this account once and within the accountExpiry time.
\nOur current supported banks are
\nIt is required to parse the provider parameter for the account you want to create. When provider is not provided, any provider account can be generated.
\n","urlObject":{"path":["create_checkout_account"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"c6426572-b7cb-47be-9d27-b120d51e5690"},{"name":"BVN Consent Request (VFD Account Only)","id":"16377b74-1936-48de-b607-1e72fe2a1440","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/bvn_consent/{bvn}","description":"It is required to call this endpoint to request BVN Consent for VFD accounts only.
\nBy calling this endpoint, a url is returned in the response for you to display for your customer to visit and complete the bvn consent approval.
\nOnce we get a successful bvn consent notification, the customer account becomes available to receive and settle payment.
\nNote: Payment made into VFD generated account will remain on hold until the customer as approve bvn consent.
\n","urlObject":{"path":["bvn_consent","{bvn}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"16377b74-1936-48de-b607-1e72fe2a1440"},{"name":"Fetch All Dedicated Virtual Account","id":"c5f94f39-7654-42f8-a55b-3786edd70a9f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/fetch_all_accounts","urlObject":{"path":["fetch_all_accounts"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"c5f94f39-7654-42f8-a55b-3786edd70a9f"},{"name":"Fetch All Dedicated Virtual Account (Specify Provider)","id":"0255b309-54c5-4911-b967-b04a345d49c4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/fetch_all_accounts/{provider}","urlObject":{"path":["fetch_all_accounts","{provider}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"0255b309-54c5-4911-b967-b04a345d49c4"},{"name":"Fetch Dedicated Virtual Account Details (By id)","id":"6efed993-60a8-4298-921d-3f77b2113957","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/fetch_account_details/{id}","urlObject":{"path":["fetch_account_details","{id}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"6efed993-60a8-4298-921d-3f77b2113957"},{"name":"Fetch Dedicated Virtual Account Details/Status (By Reference)","id":"07027c5e-30e6-4b0e-9c3d-80c74d4af7b0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/fetch_account_details/reference/{reference}","urlObject":{"path":["fetch_account_details","reference","{reference}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"07027c5e-30e6-4b0e-9c3d-80c74d4af7b0"},{"name":"Verify Transaction","id":"1a046c4d-dc76-4083-88b7-e0721802a6b5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/transaction_verify/{trx}","urlObject":{"path":["transaction_verify","{trx}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"1a046c4d-dc76-4083-88b7-e0721802a6b5"},{"name":"Check Charged Fees","id":"de3ff6c9-c3db-4cd6-a0ae-9d76b1baa37a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/check_fees","urlObject":{"path":["check_fees"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"de3ff6c9-c3db-4cd6-a0ae-9d76b1baa37a"},{"name":"Resend Failed Webhook","id":"dc1ac981-ce00-4b70-a52e-eb660339c142","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/resend_hook/{reference}","urlObject":{"path":["resend_hook","{reference}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"dc1ac981-ce00-4b70-a52e-eb660339c142"},{"name":"Refund Transaction","id":"12af0380-27b1-4d94-9c8d-550b3b015008","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"trx\":\"202211301103291623216\",\n \"note\":\"Service not rendered\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paylony.com/api/v1/refund","description":"NB: It is upto you to refund a transaction when you are unable to fulfil a customer's order on your system. You can either use this endpoint to transfer back to the exact account that sends the transaction to you or use the Bank Transfer (Payout) Endpoint to initiate your refund to a customer or an account of your choice.
\nYou can also execute this action directly from your dashboard in a single click.
\n","urlObject":{"path":["refund"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"12af0380-27b1-4d94-9c8d-550b3b015008"},{"name":"Refunds","id":"82213dd1-6c87-498b-be5b-5483be69d15f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/all_refunds","description":"This endpoint allows you to get all refunds on your business account.
\n","urlObject":{"path":["all_refunds"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"82213dd1-6c87-498b-be5b-5483be69d15f"},{"name":"Refund Status","id":"1fe186b9-583a-4318-831e-82a1552e44d9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/refund_status/{reference}","description":"This endpoint allows you to get a specific refund details on your business account.
\n","urlObject":{"path":["refund_status","{reference}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"1fe186b9-583a-4318-831e-82a1552e44d9"},{"name":"Bank List","id":"b858f486-2311-4215-9be3-70632828807f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/bank_list","urlObject":{"path":["bank_list"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"b858f486-2311-4215-9be3-70632828807f"},{"name":"Account Name Check","id":"ab33fb05-06b2-4fa5-a5bd-de11562090ea","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"bank_code\": \"000013\",\n \"account_number\": \"0050883605\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paylony.com/api/v1/account_name","description":"","urlObject":{"path":["account_name"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"ab33fb05-06b2-4fa5-a5bd-de11562090ea"},{"name":"Bank Transfer","id":"decd0eb3-6fb5-4b1d-a311-ebd0ca2c7ac0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"POST","header":[{"key":"Signature","value":"76095685de6f0f5668503be788aa858c420ea17f5fd0b5287289f530e52eadf801ce54aa31f85b4ee85f0616f5afdb63b85bf012093e821e80ec11ace79df693","type":"text"}],"body":{"mode":"raw","raw":"{\n \"account_number\":\"1019651961\",\n \"amount\":\"100\",\n \"bank_code\":\"999999\",\n \"narration\":\"Thank you\",\n \"reference\":\"2022121216014832747\",\n \"sender_name\":\"Tolulope Oyeniyi\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paylony.com/api/v1/bank_transfer","description":"YIt is required to encryption your payload using your Encryption Key and perform an HMAC-512 encryption having your payload parameters arranged alphabetically and pass the result of the encryption in the header as Signature.
\n","urlObject":{"path":["bank_transfer"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"decd0eb3-6fb5-4b1d-a311-ebd0ca2c7ac0"},{"name":"Fetch All Transfers","id":"5551ce06-aede-4c94-9140-8b9084c218f3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/fetch_all_transfers","urlObject":{"path":["fetch_all_transfers"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"5551ce06-aede-4c94-9140-8b9084c218f3"},{"name":"Fetch Transfer Details/Status","id":"7df2c06d-831d-487c-9878-12649afa2bce","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/fetch_transfer_details/{reference}","urlObject":{"path":["fetch_transfer_details","{reference}"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"7df2c06d-831d-487c-9878-12649afa2bce"},{"name":"Wallet Balance","id":"b2cd58ab-cee2-4a01-90ac-39e8fcb60381","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/wallet_balance","description":"Get Business Wallet Balance
\n","urlObject":{"path":["wallet_balance"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"b2cd58ab-cee2-4a01-90ac-39e8fcb60381"},{"name":"BVN Account Name Match","id":"c97e2259-0666-4390-8782-2e523421bda6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"firstname\":\"Tolulope\",\n \"lastname\":\"Oyeniyi\",\n \"account_number\":\"0050883605\",\n \"bank_code\":\"000013\",\n \"bvn\":\"00000000000\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paylony.com/api/v1/account_bvn_match","description":"","urlObject":{"path":["account_bvn_match"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"c97e2259-0666-4390-8782-2e523421bda6"},{"name":"BVN Verification","id":"baf3640b-955a-4661-84ef-0e3a291a32fc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"bvn\":\"00000000000\"\n}","options":{"raw":{"language":"json"}}},"url":"https://api.paylony.com/api/v1/bvn_verification","description":"","urlObject":{"path":["bvn_verification"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"baf3640b-955a-4661-84ef-0e3a291a32fc"},{"name":"BVN History","id":"a733bcf3-114d-4896-8852-8353c2bf10ce","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx"}]},"isInherited":false},"method":"GET","header":[],"url":"https://api.paylony.com/api/v1/bvn_history","urlObject":{"path":["bvn_history"],"host":["https://api.paylony.com/api/v1"],"query":[],"variable":[]}},"response":[],"_postman_id":"a733bcf3-114d-4896-8852-8353c2bf10ce"}],"event":[{"listen":"prerequest","script":{"id":"ceaf185b-bf8a-4af8-b390-1a377de6a2a6","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"3677c5dd-a081-4380-a4d2-90b40551b639","type":"text/javascript","exec":[""]}}],"variable":[{"key":"base_url","value":"https://api.paylony.com/api/v1","type":"string"},{"key":"sk","value":"sk_test_xxxxxxxxxxxxxxxxxxxxxx","type":"string"}]}