Charges

The Charge object represents a payment transaction. Creating a charge is the fundamental way to accept a payment with Payonify. A charge can be created with minimal information and then confirmed later, or created with complete payment information for immediate processing.

List all charges

GET

https://api.payonify.com

/v1/charges

Returns a paginated list of charges. The charges are returned sorted by creation date, with the most recently created charges appearing first.

Using pagination

By default, this endpoint returns 10 charges per page. You can adjust this with the limit parameter and navigate through pages using the after cursor returned in the paging object.

Code
GET /v1/charges?limit=5&after=cursor_xyz789

List all charges › query Parameters

limit

integer · min: 1 · max: 100

Number of records to return per page. Use with cursor-based pagination.

Default: 10

first

integer · min: 1 · max: 100

Number of records to return for forward pagination. Use with after cursor.

after

string

Cursor for forward pagination. Returns records after this cursor.

last

integer · min: 1 · max: 100

Number of records to return for backward pagination. Use with before cursor.

before

string

Cursor for backward pagination. Returns records before this cursor.

status

string · enum

Filter charges by status.

Enum values:

requires_payment_method

requires_authorization

pending

succeeded

failed

cancelled

currency

string · enum

Filter charges by currency ISO code.

Enum values:

usd

zwg

start_date

string · date

Filter charges created on or after this date. Use ISO 8601 format (YYYY-MM-DD).

end_date

string · date

Filter charges created on or before this date. Use ISO 8601 format (YYYY-MM-DD).

List all charges › Responses

A list of charges

ChargeList

object

string

Type of the returned object.

Charge[]

Array of charge objects.

object

Pagination metadata

GET/v1/charges

curl https://api.payonify.com/v1/charges \
  --header 'Authorization: Basic <credentials>'

Example Responses

{
  "object": "list",
  "data": [
    {
      "id": "ch_qtagfvjjpm3bja3fkekgm5u7",
      "object": "charge",
      "amount": {
        "value": 6896,
        "currency": "usd"
      },
      "livemode": false,
      "created": 1746702317,
      "paid": false,
      "metadata": {
        "order_description": "Ergonomic Fresh Mouse",
        "order_id": "5"
      },
      "client_secret": "ch_qtagfvjjpm3bja3fkekgm5u7_secret_4qx6i4xj7rwuypu3gfbdpem5vyg645lu",
      "payment_method": "mobile_money",
      "description": "Awesome Cotton Gloves",
      "receipt_email": "Jefferey50@yahoo.com",
      "return_url": "http://kaden.name",
      "statement_descriptor": "directional",
      "shipping": {
        "name": "Lelah",
        "carrier": "Fedex",
        "tracking_number": "rzn1ip1xhlssc65zum9m",
        "phone": "759.728.6676 x259",
        "address": {
          "city": "Port Jerryburgh",
          "country": "ZW",
          "line1": "2245 Rosanna Creek",
          "line2": "Apt. 408",
          "province": "North Dakota"
        }
      },
      "refund_reference": null,
      "status": "requires_authorization",
      "failure_code": null,
      "failure_reason": null,
      "cancelled_at": null,
      "cancellation_reason": null,
      "payment_method_details": {
        "type": "mobile_money",
        "mobile_money": {
          "type": "c2b",
          "reference": null,
          "brand": "ecocash",
          "customer_number": "771111111",
          "merchant_code": "019919",
          "merchant_number": "783361344",
          "merchant_name": "Test Merchant",
          "head_name": "BancABC Head Merchant",
          "network": "Econet"
        }
      }
    }
  ],
  "paging": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": null,
    "end_cursor": null,
    "page_size": 10
  }
}

json

application/json

Create a new charge

POST

https://api.payonify.com

/v1/charges

Creates a new charge object. The charge can be created with minimal information and then confirmed later, or created with complete payment information for immediate processing.

Request Body Example

Complete charge with all details and immediate confirmation:


Code
{
  "amount": 6896,
  "currency": "usd",
  "source": "pos",
  "description": "Awesome Cotton Gloves",
  "payment_method": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  },
  "metadata": {
    "order_id": "5",
    "order_description": "Ergonomic Fresh Mouse"
  },
  "receipt_email": "customer@example.com",
  "shipping": {
    "name": "Lelah",
    "carrier": "Fedex",
    "tracking_number": "rzn1ip1xhlssc65zum9m",
    "phone": "759.728.6676 x259",
    "address": {
      "city": "Port Jerryburgh",
      "country": "ZW",
      "line1": "2245 Rosanna Creek",
      "line2": "Apt. 408",
      "province": "North Dakota"
    }
  },
  "return_url": "http://example.com/return",
  "statement_descriptor": "directional",
  "confirm": true
}

Basic charge with minimal required fields:


Code
{
  "amount": 829,
  "currency": "usd",
  "source": "pos"
}

Create a new charge › Request Body

ChargeCreateRequest

amount

integer · min: 100 · required

A positive integer representing how much to be collected by this payment in its smallest unit (e.g. 100 cents to charge $1.00).

The minimum amount that can be charged is 100 (e.g., $1.00).

currency

string · enum · required

A three-letter ISO currency code. Currently, only usd and zwg are supported.

For USD transactions, 100 = $1.00 For ZWG transactions, 100 = ZWG 1.00

Enum values:

zwg

usd

source

string · enum · required

The source of the charge request. This indicates where the charge is originating from.

pos: Point of Sale system
web: Web application
mobile: Mobile application
ussd: USSD service

Enum values:

pos

web

mobile

ussd

description

string · minLength: 4 · maxLength: 150

Additional information about the charge. This will be displayed to the customer and can be used for your internal reference.

The description must be between 4 and 150 characters.

PaymentMethod

Payment method details for charges. Charges only support mobile money payment methods (EcoCash and OneMoney).

For card payments (Visa, Mastercard, Zimswitch), use Checkout Sessions instead.

This object allows you to specify which payment method to use and provide the necessary details required by that payment method.

object · maxProps: 5

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the charge in a structured way.

You can specify up to 5 keys, with key names up to 40 characters long and values up to 500 characters long.

Metadata is not displayed to the customer.

confirm

boolean

Whether to immediately attempt to confirm the charge. When true, payment method details must be included in the request.

If false or not provided, the charge will be created in a requires_payment_method state and will need to be confirmed later using the Confirm Charge endpoint.

Default: false

receipt_email

string · email

Email address where the receipt for this charge will be sent. A receipt will be sent automatically when the charge is successful.

statement_descriptor

string · minLength: 4 · maxLength: 22

Text that appears on the customer's statement. This can be used to identify the charge on the customer's bank or mobile money statement.

The statement descriptor must be between 4 and 22 characters and can only include alphanumeric characters and spaces.

Shipping

Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.

This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.

return_url

string · uri

URL to redirect the customer to after they complete their payment. This is typically used for web and mobile payments that require customer interaction to complete.

Create a new charge › Responses

Charge created successfully

A charge represents a payment transaction. Creating a charge is the fundamental way to accept a payment with Payonify. A charge can be in various states throughout its lifecycle, from creation to completion or cancellation. The `status` field indicates where the charge is in this process.

Charge

id

string

Unique identifier for the charge object. This ID is used to reference the charge in other API calls.

object

string

A string representing the type of the object. Always "charge" for charge objects.

object

Contains the monetary value and currency information for the charge.

livemode

boolean

A boolean that shows where the objects exist. true if it exists in live mode and false if it exists in test mode.

This helps distinguish between test transactions and real payments.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

This timestamp can be used to track when the charge was initially created.

paid

boolean

A boolean to show that the charge succeeded if true and failed if false.

This is a quick way to check if the payment was successfully completed.

object

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the charge in a structured way.

Metadata is not displayed to the customer and can be used for your internal systems to track orders, correlate with other systems, etc.

client_secret

string

This is a client secret for this charge. It is used by the frontend to complete a payment. It should be kept secret at all times. TLS should be used whenever you use it in the frontend.

The client secret is used when implementing client-side confirmation of payments.

payment_method

string

String representation of the payment method used. This indicates which payment method type was used to complete the transaction.

For mobile money payments, this will be "mobile_money".

description

string

String to add any more information about the charge. This can be used to provide additional context about what the payment is for.

receipt_email

string

This is the email address where the receipt for this charge was sent to.

When provided, an automated receipt will be sent to this email address after the payment is successfully completed.

return_url

string

URL to redirect the customer to after they complete their payment.

This is particularly important for payment flows that require redirection to complete the transaction.

statement_descriptor

string

Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.

Shipping

Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.

This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.

refund_reference

string

Refund reference if this charge is refunded. This field will be populated if a refund has been issued for this charge.

If no refund has been issued, this field will be null.

status

string · enum

The status of the payment. This field indicates where the charge is in the payment lifecycle.

Possible values:

requires_payment_method: The charge has been created but no payment method has been provided yet.
requires_authorization: The charge requires authorization from the customer.
pending: The charge is in the process of being completed.
succeeded: The charge completed successfully.
failed: The charge was attempted but failed.
cancelled: The charge was cancelled.

Enum values:

requires_payment_method

requires_authorization

pending

succeeded

failed

cancelled

failure_code

string

Error code for a failed charge. This field will be populated only if the charge failed. The code can be used to programmatically handle specific error cases.

If the charge was processed successfully, this field will be null.

failure_reason

string

A human-readable message providing more details about why the charge failed. This message can be displayed to the user or used for debugging.

If the charge was processed successfully, this field will be null.

cancelled_at

integer

Time at which the charge was cancelled. This is only populated if the charge has status cancelled. Measured in seconds since the Unix epoch.

For charges that haven't been cancelled, this field will be null.

cancellation_reason

string · enum

Reason for cancellation of this charge. This is only populated if the charge has been cancelled.

Possible values:

duplicate: The charge was a duplicate of another charge
fraudulent: The charge was fraudulent
abandoned: The customer abandoned the payment
requested_by_customer: The customer requested the cancellation

For charges that haven't been cancelled, this field will be null.

Enum values:

duplicate

fraudulent

abandoned

requested_by_customer

object

Contains information about the payment method used. This object provides detailed information about how the payment was processed.

The structure of this object depends on the payment method used. It will contain either a mobile_money or card object depending on the payment type.

Note: Card payments (Visa, Mastercard, Zimswitch) are only available through Checkout Sessions. Charges only support mobile money.

POST/v1/charges

curl https://api.payonify.com/v1/charges \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <credentials>' \
  --data '{
  "amount": 6896,
  "currency": "usd",
  "source": "pos",
  "description": "Awesome Cotton Gloves",
  "payment_method": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  },
  "metadata": {
    "order_id": "5",
    "order_description": "Ergonomic Fresh Mouse"
  },
  "confirm": true
}'

Example Request Body

{
  "amount": 6896,
  "currency": "usd",
  "source": "pos",
  "description": "Awesome Cotton Gloves",
  "payment_method": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  },
  "metadata": {
    "order_id": "5",
    "order_description": "Ergonomic Fresh Mouse"
  },
  "confirm": true
}

json

application/json

Example Responses

{
  "id": "ch_qtagfvjjpm3bja3fkekgm5u7",
  "object": "charge",
  "amount": {
    "value": 6896,
    "currency": "usd"
  },
  "livemode": false,
  "created": 1746702317,
  "paid": false,
  "metadata": {
    "order_description": "Ergonomic Fresh Mouse",
    "order_id": "5"
  },
  "client_secret": "ch_qtagfvjjpm3bja3fkekgm5u7_secret_4qx6i4xj7rwuypu3gfbdpem5vyg645lu",
  "payment_method": "mobile_money",
  "description": "Awesome Cotton Gloves",
  "receipt_email": "Jefferey50@yahoo.com",
  "return_url": "http://kaden.name",
  "statement_descriptor": "directional",
  "shipping": {
    "name": "Lelah",
    "carrier": "Fedex",
    "tracking_number": "rzn1ip1xhlssc65zum9m",
    "phone": "759.728.6676 x259",
    "address": {
      "city": "Port Jerryburgh",
      "country": "ZW",
      "line1": "2245 Rosanna Creek",
      "line2": "Apt. 408",
      "province": "North Dakota"
    }
  },
  "refund_reference": null,
  "status": "requires_authorization",
  "failure_code": null,
  "failure_reason": null,
  "cancelled_at": null,
  "cancellation_reason": null,
  "payment_method_details": {
    "type": "mobile_money",
    "mobile_money": {
      "type": "c2b",
      "reference": null,
      "brand": "ecocash",
      "customer_number": "771111111",
      "merchant_code": "019919",
      "merchant_number": "783361344",
      "merchant_name": "Test Merchant",
      "head_name": "BancABC Head Merchant",
      "network": "Econet"
    }
  }
}

json

application/json

Retrieve a charge

GET

https://api.payonify.com

/v1/charges/{id}

Retrieves the details of an existing charge. You can use this endpoint to check the status of a charge.

Charge status

A charge can have one of the following statuses:

requires_payment_method: The charge has been created but no payment method has been provided yet.
requires_authorization: The charge requires authorization from the customer.
pending: The charge is in the process of being completed.
succeeded: The charge completed successfully.
failed: The charge was attempted but failed.
cancelled: The charge was cancelled.

Retrieve a charge › path Parameters

id

string · required

Unique identifier for the charge

Retrieve a charge › Responses

Charge details retrieved successfully

Charge

id

string

Unique identifier for the charge object. This ID is used to reference the charge in other API calls.

object

string

A string representing the type of the object. Always "charge" for charge objects.

object

Contains the monetary value and currency information for the charge.

livemode

boolean

A boolean that shows where the objects exist. true if it exists in live mode and false if it exists in test mode.

This helps distinguish between test transactions and real payments.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

This timestamp can be used to track when the charge was initially created.

paid

boolean

A boolean to show that the charge succeeded if true and failed if false.

This is a quick way to check if the payment was successfully completed.

object

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the charge in a structured way.

Metadata is not displayed to the customer and can be used for your internal systems to track orders, correlate with other systems, etc.

client_secret

string

This is a client secret for this charge. It is used by the frontend to complete a payment. It should be kept secret at all times. TLS should be used whenever you use it in the frontend.

The client secret is used when implementing client-side confirmation of payments.

payment_method

string

String representation of the payment method used. This indicates which payment method type was used to complete the transaction.

For mobile money payments, this will be "mobile_money".

description

string

String to add any more information about the charge. This can be used to provide additional context about what the payment is for.

receipt_email

string

This is the email address where the receipt for this charge was sent to.

When provided, an automated receipt will be sent to this email address after the payment is successfully completed.

return_url

string

URL to redirect the customer to after they complete their payment.

This is particularly important for payment flows that require redirection to complete the transaction.

statement_descriptor

string

Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.

Shipping

Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.

This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.

refund_reference

string

Refund reference if this charge is refunded. This field will be populated if a refund has been issued for this charge.

If no refund has been issued, this field will be null.

status

string · enum

The status of the payment. This field indicates where the charge is in the payment lifecycle.

Possible values:

requires_payment_method: The charge has been created but no payment method has been provided yet.
requires_authorization: The charge requires authorization from the customer.
pending: The charge is in the process of being completed.
succeeded: The charge completed successfully.
failed: The charge was attempted but failed.
cancelled: The charge was cancelled.

Enum values:

requires_payment_method

requires_authorization

pending

succeeded

failed

cancelled

failure_code

string

Error code for a failed charge. This field will be populated only if the charge failed. The code can be used to programmatically handle specific error cases.

If the charge was processed successfully, this field will be null.

failure_reason

string

A human-readable message providing more details about why the charge failed. This message can be displayed to the user or used for debugging.

If the charge was processed successfully, this field will be null.

cancelled_at

integer

Time at which the charge was cancelled. This is only populated if the charge has status cancelled. Measured in seconds since the Unix epoch.

For charges that haven't been cancelled, this field will be null.

cancellation_reason

string · enum

Reason for cancellation of this charge. This is only populated if the charge has been cancelled.

Possible values:

duplicate: The charge was a duplicate of another charge
fraudulent: The charge was fraudulent
abandoned: The customer abandoned the payment
requested_by_customer: The customer requested the cancellation

For charges that haven't been cancelled, this field will be null.

Enum values:

duplicate

fraudulent

abandoned

requested_by_customer

object

Contains information about the payment method used. This object provides detailed information about how the payment was processed.

The structure of this object depends on the payment method used. It will contain either a mobile_money or card object depending on the payment type.

Note: Card payments (Visa, Mastercard, Zimswitch) are only available through Checkout Sessions. Charges only support mobile money.

GET/v1/charges/{id}

curl https://api.payonify.com/v1/charges/:id \
  --header 'Authorization: Basic <credentials>'

Example Responses

{
  "id": "ch_qtagfvjjpm3bja3fkekgm5u7",
  "object": "charge",
  "amount": {
    "value": 6896,
    "currency": "usd"
  },
  "livemode": false,
  "created": 1746702317,
  "paid": false,
  "metadata": {
    "order_description": "Ergonomic Fresh Mouse",
    "order_id": "5"
  },
  "client_secret": "ch_qtagfvjjpm3bja3fkekgm5u7_secret_4qx6i4xj7rwuypu3gfbdpem5vyg645lu",
  "payment_method": "mobile_money",
  "description": "Awesome Cotton Gloves",
  "receipt_email": "Jefferey50@yahoo.com",
  "return_url": "http://kaden.name",
  "statement_descriptor": "directional",
  "shipping": {
    "name": "Lelah",
    "carrier": "Fedex",
    "tracking_number": "rzn1ip1xhlssc65zum9m",
    "phone": "759.728.6676 x259",
    "address": {
      "city": "Port Jerryburgh",
      "country": "ZW",
      "line1": "2245 Rosanna Creek",
      "line2": "Apt. 408",
      "province": "North Dakota"
    }
  },
  "refund_reference": null,
  "status": "requires_authorization",
  "failure_code": null,
  "failure_reason": null,
  "cancelled_at": null,
  "cancellation_reason": null,
  "payment_method_details": {
    "type": "mobile_money",
    "mobile_money": {
      "type": "c2b",
      "reference": null,
      "brand": "ecocash",
      "customer_number": "771111111",
      "merchant_code": "019919",
      "merchant_number": "783361344",
      "merchant_name": "Test Merchant",
      "head_name": "BancABC Head Merchant",
      "network": "Econet"
    }
  }
}

json

application/json

Confirm a charge

POST

https://api.payonify.com

/v1/charges/{id}/confirm

Confirms a previously created charge by providing payment details.

This endpoint is used when you've created a charge with the minimum required fields (amount, currency, source) and now want to complete it by adding payment details.

Request Body Example


Code
{
  "description": "Small Plastic Pants",
  "payment_method": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  },
  "receipt_email": "customer@example.com",
  "shipping": {
    "name": "Destany",
    "carrier": "Fedex",
    "tracking_number": "hw4r0m6aqtzdz8ksqm42",
    "phone": "(559) 298-7733",
    "address": {
      "city": "Jerdeside",
      "country": "ZW",
      "line1": "782 Timmothy Shores",
      "line2": "Suite 982",
      "province": "Illinois"
    }
  },
  "return_url": "http://example.com/return"
}

Confirm a charge › path Parameters

id

string · required

Unique identifier for the charge

Confirm a charge › Request Body

ChargeConfirmRequest

PaymentMethod · required

Payment method details for charges. Charges only support mobile money payment methods (EcoCash and OneMoney).

For card payments (Visa, Mastercard, Zimswitch), use Checkout Sessions instead.

This object allows you to specify which payment method to use and provide the necessary details required by that payment method.

description

string · minLength: 4 · maxLength: 150

Additional information about the charge. This will be displayed to the customer and can be used for your internal reference.

The description must be between 4 and 150 characters.

object · maxProps: 5

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the charge in a structured way.

You can specify up to 5 keys, with key names up to 40 characters long and values up to 500 characters long.

receipt_email

string · email

Email address where the receipt for this charge will be sent. A receipt will be sent automatically when the charge is successful.

statement_descriptor

string · minLength: 4 · maxLength: 22

Text that appears on the customer's statement. This can be used to identify the charge on the customer's bank or mobile money statement.

The statement descriptor must be between 4 and 22 characters and can only include alphanumeric characters and spaces.

Shipping

Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.

This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.

return_url

string · uri

URL to redirect the customer to after they complete their payment. This is typically used for web and mobile payments that require customer interaction to complete.

Confirm a charge › Responses

Charge confirmed successfully

Charge

id

string

Unique identifier for the charge object. This ID is used to reference the charge in other API calls.

object

string

A string representing the type of the object. Always "charge" for charge objects.

object

Contains the monetary value and currency information for the charge.

livemode

boolean

A boolean that shows where the objects exist. true if it exists in live mode and false if it exists in test mode.

This helps distinguish between test transactions and real payments.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

This timestamp can be used to track when the charge was initially created.

paid

boolean

A boolean to show that the charge succeeded if true and failed if false.

This is a quick way to check if the payment was successfully completed.

object

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the charge in a structured way.

Metadata is not displayed to the customer and can be used for your internal systems to track orders, correlate with other systems, etc.

client_secret

string

This is a client secret for this charge. It is used by the frontend to complete a payment. It should be kept secret at all times. TLS should be used whenever you use it in the frontend.

The client secret is used when implementing client-side confirmation of payments.

payment_method

string

String representation of the payment method used. This indicates which payment method type was used to complete the transaction.

For mobile money payments, this will be "mobile_money".

description

string

String to add any more information about the charge. This can be used to provide additional context about what the payment is for.

receipt_email

string

This is the email address where the receipt for this charge was sent to.

When provided, an automated receipt will be sent to this email address after the payment is successfully completed.

return_url

string

URL to redirect the customer to after they complete their payment.

This is particularly important for payment flows that require redirection to complete the transaction.

statement_descriptor

string

Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.

Shipping

Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.

This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.

refund_reference

string

Refund reference if this charge is refunded. This field will be populated if a refund has been issued for this charge.

If no refund has been issued, this field will be null.

status

string · enum

The status of the payment. This field indicates where the charge is in the payment lifecycle.

Possible values:

requires_payment_method: The charge has been created but no payment method has been provided yet.
requires_authorization: The charge requires authorization from the customer.
pending: The charge is in the process of being completed.
succeeded: The charge completed successfully.
failed: The charge was attempted but failed.
cancelled: The charge was cancelled.

Enum values:

requires_payment_method

requires_authorization

pending

succeeded

failed

cancelled

failure_code

string

Error code for a failed charge. This field will be populated only if the charge failed. The code can be used to programmatically handle specific error cases.

If the charge was processed successfully, this field will be null.

failure_reason

string

A human-readable message providing more details about why the charge failed. This message can be displayed to the user or used for debugging.

If the charge was processed successfully, this field will be null.

cancelled_at

integer

Time at which the charge was cancelled. This is only populated if the charge has status cancelled. Measured in seconds since the Unix epoch.

For charges that haven't been cancelled, this field will be null.

cancellation_reason

string · enum

Reason for cancellation of this charge. This is only populated if the charge has been cancelled.

Possible values:

duplicate: The charge was a duplicate of another charge
fraudulent: The charge was fraudulent
abandoned: The customer abandoned the payment
requested_by_customer: The customer requested the cancellation

For charges that haven't been cancelled, this field will be null.

Enum values:

duplicate

fraudulent

abandoned

requested_by_customer

object

Contains information about the payment method used. This object provides detailed information about how the payment was processed.

The structure of this object depends on the payment method used. It will contain either a mobile_money or card object depending on the payment type.

Note: Card payments (Visa, Mastercard, Zimswitch) are only available through Checkout Sessions. Charges only support mobile money.

POST/v1/charges/{id}/confirm

curl https://api.payonify.com/v1/charges/:id/confirm \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <credentials>' \
  --data '{
  "payment_method": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  }
}'

Example Request Body

{
  "payment_method": {
    "mobile_money": {
      "ecocash": {
        "mobile_number": "771111111"
      }
    }
  }
}

json

application/json

Example Responses

{
  "id": "ch_qtagfvjjpm3bja3fkekgm5u7",
  "object": "charge",
  "amount": {
    "value": 6896,
    "currency": "usd"
  },
  "livemode": false,
  "created": 1746702317,
  "paid": false,
  "metadata": {
    "order_description": "Ergonomic Fresh Mouse",
    "order_id": "5"
  },
  "client_secret": "ch_qtagfvjjpm3bja3fkekgm5u7_secret_4qx6i4xj7rwuypu3gfbdpem5vyg645lu",
  "payment_method": "mobile_money",
  "description": "Awesome Cotton Gloves",
  "receipt_email": "Jefferey50@yahoo.com",
  "return_url": "http://kaden.name",
  "statement_descriptor": "directional",
  "shipping": {
    "name": "Lelah",
    "carrier": "Fedex",
    "tracking_number": "rzn1ip1xhlssc65zum9m",
    "phone": "759.728.6676 x259",
    "address": {
      "city": "Port Jerryburgh",
      "country": "ZW",
      "line1": "2245 Rosanna Creek",
      "line2": "Apt. 408",
      "province": "North Dakota"
    }
  },
  "refund_reference": null,
  "status": "requires_authorization",
  "failure_code": null,
  "failure_reason": null,
  "cancelled_at": null,
  "cancellation_reason": null,
  "payment_method_details": {
    "type": "mobile_money",
    "mobile_money": {
      "type": "c2b",
      "reference": null,
      "brand": "ecocash",
      "customer_number": "771111111",
      "merchant_code": "019919",
      "merchant_number": "783361344",
      "merchant_name": "Test Merchant",
      "head_name": "BancABC Head Merchant",
      "network": "Econet"
    }
  }
}

json

application/json

Cancel a charge

POST

https://api.payonify.com

/v1/charges/{id}/cancel

Cancels a previously created charge. You can only cancel charges that haven't been completed yet.

Cancellation reasons

You can specify a reason for cancellation, which is useful for record-keeping:

duplicate: The charge was a duplicate of another charge
fraudulent: The charge was fraudulent
abandoned: The customer abandoned the payment
requested_by_customer: The customer requested the cancellation

Request Body Example


Code
{
  "cancellation_reason": "fraudulent"
}

Cancel a charge › path Parameters

id

string · required

Unique identifier for the charge

Cancel a charge › Request Body

ChargeCancelRequest

cancellation_reason

string · enum

Reason for cancelling the charge. This helps with record-keeping and can be useful for tracking why charges were cancelled.

Enum values:

duplicate

fraudulent

abandoned

requested_by_customer

Cancel a charge › Responses

Charge cancelled successfully

Charge

id

string

Unique identifier for the charge object. This ID is used to reference the charge in other API calls.

object

string

A string representing the type of the object. Always "charge" for charge objects.

object

Contains the monetary value and currency information for the charge.

livemode

boolean

A boolean that shows where the objects exist. true if it exists in live mode and false if it exists in test mode.

This helps distinguish between test transactions and real payments.

created

integer

Time at which the object was created. Measured in seconds since the Unix epoch.

This timestamp can be used to track when the charge was initially created.

paid

boolean

A boolean to show that the charge succeeded if true and failed if false.

This is a quick way to check if the payment was successfully completed.

object

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the charge in a structured way.

Metadata is not displayed to the customer and can be used for your internal systems to track orders, correlate with other systems, etc.

client_secret

string

This is a client secret for this charge. It is used by the frontend to complete a payment. It should be kept secret at all times. TLS should be used whenever you use it in the frontend.

The client secret is used when implementing client-side confirmation of payments.

payment_method

string

String representation of the payment method used. This indicates which payment method type was used to complete the transaction.

For mobile money payments, this will be "mobile_money".

description

string

String to add any more information about the charge. This can be used to provide additional context about what the payment is for.

receipt_email

string

This is the email address where the receipt for this charge was sent to.

When provided, an automated receipt will be sent to this email address after the payment is successfully completed.

return_url

string

URL to redirect the customer to after they complete their payment.

This is particularly important for payment flows that require redirection to complete the transaction.

statement_descriptor

string

Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.

Shipping

Shipping information for the charge. This object contains delivery details for physical goods, including the recipient's name, address, and shipping method.

This information is optional but recommended for charges related to physical goods to help with order tracking and delivery.

refund_reference

string

Refund reference if this charge is refunded. This field will be populated if a refund has been issued for this charge.

If no refund has been issued, this field will be null.

status

string · enum

The status of the payment. This field indicates where the charge is in the payment lifecycle.

Possible values:

requires_payment_method: The charge has been created but no payment method has been provided yet.
requires_authorization: The charge requires authorization from the customer.
pending: The charge is in the process of being completed.
succeeded: The charge completed successfully.
failed: The charge was attempted but failed.
cancelled: The charge was cancelled.

Enum values:

requires_payment_method

requires_authorization

pending

succeeded

failed

cancelled

failure_code

string

Error code for a failed charge. This field will be populated only if the charge failed. The code can be used to programmatically handle specific error cases.

If the charge was processed successfully, this field will be null.

failure_reason

string

A human-readable message providing more details about why the charge failed. This message can be displayed to the user or used for debugging.

If the charge was processed successfully, this field will be null.

cancelled_at

integer

Time at which the charge was cancelled. This is only populated if the charge has status cancelled. Measured in seconds since the Unix epoch.

For charges that haven't been cancelled, this field will be null.

cancellation_reason

string · enum

Reason for cancellation of this charge. This is only populated if the charge has been cancelled.

Possible values:

duplicate: The charge was a duplicate of another charge
fraudulent: The charge was fraudulent
abandoned: The customer abandoned the payment
requested_by_customer: The customer requested the cancellation

For charges that haven't been cancelled, this field will be null.

Enum values:

duplicate

fraudulent

abandoned

requested_by_customer

object

Contains information about the payment method used. This object provides detailed information about how the payment was processed.

The structure of this object depends on the payment method used. It will contain either a mobile_money or card object depending on the payment type.

Note: Card payments (Visa, Mastercard, Zimswitch) are only available through Checkout Sessions. Charges only support mobile money.

POST/v1/charges/{id}/cancel

curl https://api.payonify.com/v1/charges/:id/cancel \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <credentials>' \
  --data '{
  "cancellation_reason": "requested_by_customer"
}'

Example Request Body

{
  "cancellation_reason": "requested_by_customer"
}

json

application/json

Example Responses

{
  "id": "ch_qtagfvjjpm3bja3fkekgm5u7",
  "object": "charge",
  "amount": {
    "value": 6896,
    "currency": "usd"
  },
  "livemode": false,
  "created": 1746702317,
  "paid": false,
  "metadata": {
    "order_description": "Ergonomic Fresh Mouse",
    "order_id": "5"
  },
  "client_secret": "ch_qtagfvjjpm3bja3fkekgm5u7_secret_4qx6i4xj7rwuypu3gfbdpem5vyg645lu",
  "payment_method": "mobile_money",
  "description": "Awesome Cotton Gloves",
  "receipt_email": "Jefferey50@yahoo.com",
  "return_url": "http://kaden.name",
  "statement_descriptor": "directional",
  "shipping": {
    "name": "Lelah",
    "carrier": "Fedex",
    "tracking_number": "rzn1ip1xhlssc65zum9m",
    "phone": "759.728.6676 x259",
    "address": {
      "city": "Port Jerryburgh",
      "country": "ZW",
      "line1": "2245 Rosanna Creek",
      "line2": "Apt. 408",
      "province": "North Dakota"
    }
  },
  "refund_reference": null,
  "status": "requires_authorization",
  "failure_code": null,
  "failure_reason": null,
  "cancelled_at": null,
  "cancellation_reason": null,
  "payment_method_details": {
    "type": "mobile_money",
    "mobile_money": {
      "type": "c2b",
      "reference": null,
      "brand": "ecocash",
      "customer_number": "771111111",
      "merchant_code": "019919",
      "merchant_number": "783361344",
      "merchant_name": "Test Merchant",
      "head_name": "BancABC Head Merchant",
      "network": "Econet"
    }
  }
}

json

application/json

Refunds