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 param
    • price : Price of the item account to currency format. Required param
    • image : 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

POST
/payments/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

GET
/payments/:reference
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:

    1. cm.mtn: For MTN Mobile Money Cameroun
    2. cm.orange: For Orange Money Cameroun
    3. cm.mobile: For Orange Money Or MTN Mobile Money Cameroon only
    4. paypal: For PayPal
    5. Card: For Visa, Mastercard, Amex, etc.
  • Name
    data
    Type
    object
    Description

    Customer information relating to the chosen payment method.

Data parameters according to channel

  1. cm.mtn
    • phone : MTN Mobile mobile money number to be charged
  2. cm.orange
    • phone : Orange money number to be charged
  3. cm.mobile
    • phone : MTN Mobile or Orange money number to be charged
  4. paypal
    • email : Customer email
  5. card
    • name : Card Holder Name
    • card_number : Card Number
    • exp : Card Expire date (MM/YY)
    • cvc : Card Verification Code

Complete

PUT
/payments/:reference
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

GET
/payments
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

DELETE
/payments/:reference
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"
}