Payments

The Payments API facilitates the creation and management of payment processes within your integrated system.

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 URL to redirect the customer to after status update

  • 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"
}