API Introduction

The Paycoinly APi system is very easy to integrate. With very basic knowledge of programming or even basic Web design knowledge developers or designers can integrate Paycoinly. This is Version 001 the very first API service launched by Paycoinly, this API was released on the 5th of February, 2020.

To complete payment, users would be required to enter a one time password generated after the first payment call has been initiated then after the insert of the OTP if correct then Payment Is successful. OTP could be via Email or an Authenticator depends on which the user has selected. If a user inputs more than 5 wrong OTPs then the user’s account is locked for the next few hours and also if user hasn’t verified their emails it will show the respective error.

The error system has been simplified to show why the payment isn’t going through at a particular time from the ‘note‘ response. This will interpret the error code if there is one.

API Introduction

You must set your domain in your Profile. And your API connection. must be turned on also



To connect, your API status must be turned ON. Go to API Keys and make sure its on. Basic authentication here is your Public Key.


You must set your domain in your Profile. And your API connection. must be turned on also


Handling errors

Error handling is pretty simple on Paycoinly, all erros comes with a response called note. It interprets the erros and makes it readable even to the user. There might be several reasons why a payment is not going through with the note response you are able to figure it out quickly.

This API has 2 phases, the first one is the payment generation link, here all required is the basic authentication, recipient which is either the email or the account number then a payment link is generated. The second phase is where the user is required to enter the OTP for the payment Authentication.

Code Actual Meaning
100 Payment has been completed successfully
201 The user account is experiencing any of the following; haven't verified email, currency not set or account is suspended.
202 You cannot be the receiver and the sender at the same time
203 The amount the user is trying to pay is higher than his/her account balance.
204 Public key which is important is empty
205 Public key doesn't exist.
206 Api status is turned off. It needs to be turned on before you can process payments.
207 The user does not exist on Paycoinly.
208 The currency entered to accept payment does not exist.
209 The amount field cannot be empty.
210 The payment link is invalid
211 The payment link has expired. Allowed time for the customer to enter the OTP is only 15 minutes.
212 The OTP entered by the user is incorrect
213 Payment link generated has already been paid
214 Account locked due to too many wrong OTPs. Account payment is locked for 6 hours after 4 OTP fails.
215 Please generate another secret code. You cannot use the same secret code previously used.
500 The payment link has been generated. Use it to connect to the next phase.
Handling Errors
100 Success
500 Payment processed, otp required
201 This account cannot make payment
202 You cannot pay yourself
203 Balance is low
204 You did not send any Public Key
205 This Public key does not exist
206 API turned off, please turn it on from paycoinly.com/map/api-keys
207 Recipient does not exit
208 Currency is invalid
209 Amount is either empty or its invalid
210 This link is invalid
211 This link has expired
212 Wrong OTP
213 This payment has already been completed
214 Too Many Wrong OTPs. Account temporarily locked for making payments
215 Please generate another secret code

Api Requests

All the posts variables are required. Basically there are 2 part to the payment integration.

The first part is for checking if everything is okay and the user is qualified to send payments and then sends an OTP.

The second phase checks if the OTP is correct and then deducts balancne and credits the seller/merchant.

Required Post Fields

Value Description
api_public_key Your API keys
amount Amount in numbers only without a comma
currency The currency you want to accept payment from
recipient The user's email address or account number
secret A secret code to identify the transaction

Return Values

Name Return Value Meaning
status The status of payment, 100 for success, 500 for first stage processed. Check Error handling for the full list
token_link The link where the next Post is sent to
selling_amount This returns the amount you have inserted
rate This is the rate at which the conversion is done. This applies if the user is paying from another currency.
selling_currency This returns the default currency which you sent
recipient This returns the user details which you sent.
recipient_currency This returns the currency of the user paying. Example EUR
receiver_currency This is your own primary currency on Paycoinly
recipient_final_amount Final amount to be charged or that was charged. This is necessary if the selling_currency is different from the recipient_currency
recipient_currency_sign This returns the currency sign for the user. Example €
receiver_final_amount This is the amount that will be credited or that has been credited to your account.
payment_id This is the transaction ID. You can refer to this if there is any issue with the transaction to Paycoinly support.
secret This is the secret code you sent which is returned
token_expiry_date The expiry time for the link generated from step one. The validity is only 15minutes.

Step One End Point
Post Fields

Return Values For Step One
rate , 

Step Two End Point
Token Link Generated From Step One: Example 

Post Fields

Return Values For Step Two