Payments
The Payments API facilitates the creation and management of payment processes within your integrated system.
The execution of the following requests requires an authentication key. The key is present in the merchant's dashboard.
Initialize Payment
Hey there, start a transaction from Notch Pay.
Attributes
- Name
email
- Type
- string
- Description
The email address of the customer is prominently displayed within your dashboard, and serves as a valuable tool for both search and tracking purposes. Please note that this field allows for up to 512 characters.
- Name
currency
- Type
- string
- Description
Currency of transaction.
- Name
amount
- Type
- numeric
- Description
Amount to be charged for the payment. According to currency.
Optionnal attributes
- Name
name
- Type
- string
- Description
The customer’s full name or business name.
- Name
phone
- Type
- Valid phone number
- Description
The customer’s phone number.
- Name
callback
- Type
- Valid URL
- Description
The customer’s phone number.
- Name
locked_currency
- Type
- currency
- Description
The currency with which the payment information will be displayed to your customer.
- Name
locked_country
- Type
- string
- Description
Only the payment methods available for this country will be available on the payment page.
- Name
description
- Type
- string
- Description
The customer description. Please note that this field allows for up to 256 characters.
- Name
reference
- Type
- string
- Description
Unique reference for your payments
- Name
items
- Type
- array of object
- Description
A collection of objects containing:
description
: Description of the item. Required paramprice
: Price of the item account to currency format. Required paramimage
: Image of the item
- Name
customer_meta
- Type
- object
- Description
A collection of key/value pairs that can be attached to a customer for the purpose of storing additional information in a structured format.
- Name
address
- Type
- object
- Description
The customer’s address.
address.country
: Please provide the two-letter country code in accordance with ISO 3166-1 alpha-2 standard.address.city
: Please provide the name of the city, district, suburb, town, or village.address.line1
: Address line 1 (e.g., street, PO Box, or company name).address.line2
: Address line 2 (e.g., apartment, suite, unit, or building).address.postal_code
: ZIP or postal code.address.state
: State, county, province, or region.
- Name
shipping
- Type
- object
- Description
The customer’s shipping information. Appears on invoices emailed to this customer.
shipping.country
: Please provide the two-letter country code in accordance with ISO 3166-1 alpha-2 standard.shipping.city
: Please provide the name of the city, district, suburb, town, or village.shipping.line1
: Address line 1 (e.g., street, PO Box, or company name).shipping.line2
: Address line 2 (e.g., apartment, suite, unit, or building).shipping.postal_code
: ZIP or postal code.shipping.state
: State, county, province, or region.
Initialize
curl --location --request POST 'https://api.notchpay.co/payments/initialize' \
--header 'Authorization: PUBLIC_KEY' \
--header 'Accept: application/json' \
--form 'email="customer@email.com"' \
--form 'currency="XAF"' \
--form 'amount="1000"' \
--form 'phone="656019261"' \
--form 'reference="your_unique_reference"' \
--form 'description="Payment description"'
Response
{
"status": "Accepted",
"message": "Payment initialized",
"code": 201,
"transaction": {
"amount": 1000,
"amount_total": 1000,
"sandbox": false,
"fee": 0,
"converted_amount": 1000,
"business": {
"id": "9pDOCy7Rp",
"country": "CM",
"email": "hello@notchpay.co",
"phone": "+237 6 55******",
"poster": null,
"name": "Notch Africa"
},
"customer": {
"id": "ncus_ZsI7fLvDccOX",
"name": null,
"email": "customer@email.com",
"sandbox": false,
"phone": null,
"blocked": false
},
"description": "Payment description",
"reference": "XpUhSdXGBhVFVWoRRpYpAf12Ymvr1Wj6",
"merchant_reference": "your_unique_reference",
"status": "pending",
"currency": "XAF",
"initiated_at": "2023-05-14T13:39:23.000000Z",
"updated_at": "2023-05-14T13:39:23.000000Z"
},
"authorization_url": "https://pay.notchpay.co/webcheckout/XpUhSdXGBhVFVWoRRpYpAf12Ymvr1Wj6"
}
Verify and fetch Payment
Get Payment details & status
Optionnal attributes
- Name
currency
- Type
- string
- Description
Convert amount to given currency
Request
curl -G https://api.notchpay.co/payments/bWpe7YBkjBZxUzRv60iDPTQJsiVUQLRt \
-H "Authorization: {PUBLIC_KEY}"
Response
{
"code": 200,
"status": "OK",
"message": "Payment retrieved",
"transaction": {
"amount": 1000,
"amount_total": 1000,
"sandbox": false,
"fee": 0,
"converted_amount": 1000,
"business": {
"id": "9pDOCy7Rp",
"country": "CM",
"email": "hello@notchpay.co",
"phone": "+237 6 55 72 82 67",
"poster": null,
"name": "Notch Africa"
},
"customer": {
"id": "ncus_ZsI7fLvDccOX",
"name": "User test",
"email": "customer@email.com",
"sandbox": false,
"phone": null,
"blocked": false
},
"description": "Payment description",
"reference": "bWpe7YBkjBZxUzRv60iDPTQJsiVUQLRt",
"merchant_reference": "your_unique_reference2",
"status": "pending",
"currency": "XAF",
"initiated_at": "2023-05-14T14:04:53.000000Z",
"updated_at": "2023-05-14T14:04:53.000000Z"
}
}
Complete Payment
Hey there, start a transaction from Notch Pay.
Attributes
- Name
channel
- Type
- string
- Description
Payment channel to make a payment with. Available channels include:
cm.mtn
: For MTN Mobile Money Camerouncm.orange
: For Orange Money Camerouncm.mobile
: For Orange Money Or MTN Mobile MoneyCameroon only
paypal
: For PayPalCard
: For Visa, Mastercard, Amex, etc.
- Name
data
- Type
- object
- Description
Customer information relating to the chosen payment method.
Data parameters according to channel
cm.mtn
- phone : MTN Mobile mobile money number to be charged
cm.orange
- phone : Orange money number to be charged
cm.mobile
- phone : MTN Mobile or Orange money number to be charged
paypal
- email : Customer email
card
- name : Card Holder Name
- card_number : Card Number
- exp : Card Expire date (MM/YY)
- cvc : Card Verification Code
Complete
curl --location -g --request PUT 'https://api.notchpay.co/payments/cTXHSX223NhUzjgxAJoRAzVFGwBIn0Kv' \
--header 'Authorization: PUBLIC_KEY' \
--header 'Accept: application/json' \
--data '{
"channel": "cm.orange",
"data" : {
"phone": "+237656019261"
}
}'
Response
{
"message": "Confirm your transaction by dialing #150#",
"code": 202,
"status": "Accepted",
"action": "confirm"
}
List Payments
This endpoint allows you to retrieve a paginated list of all your payments. By default, a maximum of thirty payments are shown per page.
Optional attributes
- Name
perpage
- Type
- integer
- Description
Number of payments returned per page.
- Name
page
- Type
- integer
- Description
Select items on specified page
Request
curl -G https://api.notchpay.co/payments \
-H "Authorization: {PUBLIC_KEY}"
Response
{
"code": 200,
"status": "OK",
"message": "Payments retrieved",
"totals": 19,
"last_page": 1,
"current_page": 1,
"selected": 19,
"items": [
{
"amount": 1000,
"amount_total": 1000,
"sandbox": false,
"fee": 0,
"converted_amount": 1.67,
"business": {
"id": "9pDOCy7Rp",
"country": "CM",
"email": "hello@notchpay.co",
"phone": "+237 6 55 ******",
"poster": null,
"name": "Notch Africa"
},
// ...
{
"amount": 6553,
"amount_total": 6553,
"sandbox": false,
"fee": 0,
"converted_amount": 10.94,
"business": {
"id": "9pDOCy7Rp",
"country": "CM",
"email": "hello@notchpay.co",
"phone": "+237 6 55 ******",
"poster": null,
"name": "Notch Africa"
},
"customer": {
"id": "ncus_mf6lpR71Pngu",
"name": "Chapdel KAMGA",
"email": "hella@notchpay.co",
"sandbox": false,
"phone": "655******",
"blocked": false,
"address": {
"city": "Yaounde",
"line1": "Superette, Biyem Assi",
"state": "Centre",
"country": "CM"
},
"shipping": {
"city": "Yaounde",
"line1": "Superette, Biyem Assi",
"state": "Centre",
"country": "CM"
},
"metadata": {
"addess": "test"
}
},
"description": null,
"reference": "kP4r6bGdTcKI642JY1vtF3awvRk1bn6l",
"status": "pending",
"currency": "USD",
"initiated_at": "2023-05-14T12:02:12.000000Z",
"updated_at": "2023-05-14T12:02:12.000000Z"
}
]
}
Cancel Payment
Cancel a payment.
Complete
curl --location -g --request GET 'https://api.notchpay.co/payments/cTXHSX223NhUzjgxAJoRAzVFGwBIn0Kv' \
--header 'Authorization: PUBLIC_KEY' \
--header 'Accept: application/json'
Response
{
"code": 202,
"message": "Your transaction has been canceled"
}