Initiate Payment
This section describes how to initiate a payment using crypto currency on Patricia Business.
Pay With Patricia
The initialisation endpoint allows a merchant to initiate a payment intent. A successful initialisation will return a response object that has the payment_url attribute. Every data in the payload above is required, except the business_reference. Organizations can choose to bring in their own reference, in the case where they don't have any, Patricia will generate one for them.
Endpoint
POST /v1/payment/initiate
Request Object
{
"currency":"NGN",
"amount":60000,
"first_name":"John",
"last_name":"Doe",
"email":"[email protected]",
"payment_method":"crypto_bitcoin",
"business_reference":"ref_id_12345",
"metadata": {
"device": "Android"
}
}
Parameter Definition
| Parameter | Type | Required | Description |
|---|---|---|---|
| currency | string | true | The currency the merchant wishes to accept payment in. Currency must be in a three-letter ISO currency code and in uppercase. The supported currencies include "NGN", "GHC", "KES", "USD".Where NGN represents Nigerian Naira, GHC is Ghanian Cedis, KES is Kenyan Shilling and USD is US Dollars. amount integer Amount intended to be collected by the merchant. A positive integer representing how much is to be charged. Please note that currencies here are denominated in Naira and not Kobo (e.g 1 will charge N1). The minimum amount to charge is N1 and the maximum charge per transaction is N1,000,000. |
| first_name | string | true | This is the first name of the customer performing the transaction. This attribute only accepts alphanumeric characters. |
| last_name | string | true | This is the last name of the customer performing the transaction. This attribute only accepts alphanumeric characters. |
| string | true | This is the email of the customer performing the transaction. A fully valid email is expected here. Patricia Business will email the customer a transaction receipt after every successful transaction. | |
| payment_method | string | true | The payment method can be one of crypto_bitcoin, crypto_ethereum , crypto_tether , crypto_ripple , crypto_dogecoin if the merchant intends to charge their client in cryptocurrency. |
| business_reference | string | false | The business reference isn't a required parameter, this is because Patricia generates a reference for all her transaction. But in the case where a company decides to provide one, they must ensure that the said reference is unique. |
| metadata | object | false | metadata is an optional field that the merchant can use to to send additional data points that isn't supported by Patricia. These data must be an array. |
Response Object
{
"status":true,
"message":"Payment initiated successfully",
"data":{
"payment_url":"http://business.mypatricia.co/pay/xrRpfexkbSFs",
"access_token":"xrRpfexkbSFs",
"reference":"PAY_6Yta4EBTAMwIS8L",
"amount":60000,
"currency":"NGN"
}
}
Transaction Expiration.
The user has 7 minutes to complete the transaction using the
payment_linkabove, else the transaction is voided. If they intend to continue with this transaction, they will have to re-initiate a fresh transaction.
Payment method
Please note that the merchant must select either, (crypto_bitcoin)BTC, (crypto_ethereum)ETH, (crypto_tether)USDT, (crypto_ripple)XRP or (crypto_dogecoin)DOGE as their acceptable payment method before they can allow it to go through the API.
Response
| Item | Type | Description |
|---|---|---|
| status | boolean | The status here shows the state of the transaction. See below for all the possible states. A human-readable message providing more details about the error. |
| data | object | Details about the payment response at the time of the transaction. |
| data.payment_url | string | A URL where the user will be redirected to in order for them to complete their transaction. |
| data.access_token | string | The access token is used by the gateway to verify the authenticity of the transaction. All-access tokens are unique to a particular transaction. |
| data.reference | string | A unique ID that is attached to every transaction. This ID can also be shared with the user in the case where there's a dispute. |
| data.amount | integer | The amount for the transaction. |
| data.currency | string | The currency in which the transaction was made. |
Transaction States
- Pending: a transaction awaiting initiation
- Initiated: A transaction that has been initiated, i.e the customer has gotten to the gateway and has seen the details for payment
- Processing: A transaction that has received the first confirmation on the blockchain
- Successful - a transaction that has received final confirmation on the blockchain and the payment was the right amount
- Declined - A payment that has received final confirmation on the blockchain but the payment was found to be either an overpayment or an underpayment. It could also be due to the payment being made after the transaction has been considered abandoned
- Failed - A payment that failed to resolve on the blockchain. However, this is a very rare occurrence.
- Abandoned - a transaction that was initiated but wasn't acted upon within the required 24 hours
- Expired - a pending transaction that was never initiated (happens in very rare cases)
Updated almost 3 years ago