Charges

Endpoint:https://api.payonify.com

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.

Charge Endpoints

POST /v1/chargesCreate a charge POST /v1/charges/:id/confirmConfirm a charge POST /v1/charges/:id/cancelCancel a charge GET /v1/charges/:idRetrieve a charge GET /v1/chargesList all charges

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

limitinteger · min: 1 · max: 100
Number of records to return per page. Use with cursor-based pagination.
Default: 10
firstinteger · min: 1 · max: 100
Number of records to return for forward pagination. Use with after cursor.
afterstring
Cursor for forward pagination. Returns records after this cursor.
lastinteger · min: 1 · max: 100
Number of records to return for backward pagination. Use with before cursor.
beforestring
Cursor for backward pagination. Returns records before this cursor.
statusstring · enum
Filter charges by status.
Enum values:
requires_payment_method
requires_authorization
pending
succeeded
failed
cancelled
currencystring · enum
Filter charges by currency ISO code.
Enum values:
usd
zwg
start_datestring · date
Filter charges created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_datestring · date
Filter charges created on or before this date. Use ISO 8601 format (YYYY-MM-DD).

List all charges › Responses

A list of charges

objectstring
Type of the returned object.
dataobject[]
Array of charge objects.
pagingobject
Pagination metadata

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

amountinteger · 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).
currencystring · 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
sourcestring · 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

descriptionstring · 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.
payment_methodobject
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.
metadataobject · 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.
confirmboolean
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_emailstring · email
Email address where the receipt for this charge will be sent. A receipt will be sent automatically when the charge is successful.
statement_descriptorstring · 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.
shippingobject
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_urlstring · 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

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.

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

idstring · required
Unique identifier for the charge

Retrieve a charge › Responses

Charge details retrieved successfully

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.

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

idstring · required
Unique identifier for the charge

Confirm a charge › Request Body

payment_methodobject · 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.

descriptionstring · 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.
metadataobject · 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_emailstring · email
Email address where the receipt for this charge will be sent. A receipt will be sent automatically when the charge is successful.
statement_descriptorstring · 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.
shippingobject
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_urlstring · 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

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.

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

idstring · required
Unique identifier for the charge

Cancel a charge › Request Body

cancellation_reasonstring · 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

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.

Refunds

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

limitinteger · min: 1 · max: 100
Number of records to return per page. Use with cursor-based pagination.
Default: 10
firstinteger · min: 1 · max: 100
Number of records to return for forward pagination. Use with after cursor.
afterstring
Cursor for forward pagination. Returns records after this cursor.
lastinteger · min: 1 · max: 100
Number of records to return for backward pagination. Use with before cursor.
beforestring
Cursor for backward pagination. Returns records before this cursor.
statusstring · enum
Filter charges by status.
Enum values:
requires_payment_method
requires_authorization
pending
succeeded
failed
cancelled
currencystring · enum
Filter charges by currency ISO code.
Enum values:
usd
zwg
start_datestring · date
Filter charges created on or after this date. Use ISO 8601 format (YYYY-MM-DD).
end_datestring · date
Filter charges created on or before this date. Use ISO 8601 format (YYYY-MM-DD).

List all charges › Responses

A list of charges

objectstring
Type of the returned object.
dataobject[]
Array of charge objects.
pagingobject
Pagination metadata

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

amountinteger · 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).
currencystring · 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
sourcestring · 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

descriptionstring · 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.
payment_methodobject
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.
metadataobject · 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.
confirmboolean
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_emailstring · email
Email address where the receipt for this charge will be sent. A receipt will be sent automatically when the charge is successful.
statement_descriptorstring · 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.
shippingobject
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_urlstring · 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

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.

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

idstring · required
Unique identifier for the charge

Retrieve a charge › Responses

Charge details retrieved successfully

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.

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

idstring · required
Unique identifier for the charge

Confirm a charge › Request Body

payment_methodobject · 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.

descriptionstring · 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.
metadataobject · 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_emailstring · email
Email address where the receipt for this charge will be sent. A receipt will be sent automatically when the charge is successful.
statement_descriptorstring · 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.
shippingobject
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_urlstring · 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

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.

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

idstring · required
Unique identifier for the charge

Cancel a charge › Request Body

cancellation_reasonstring · 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

idstring
Unique identifier for the charge object. This ID is used to reference the charge in other API calls.
objectstring
A string representing the type of the object. Always "charge" for charge objects.
amountobject
Contains the monetary value and currency information for the charge.
livemodeboolean
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.
createdinteger
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.
paidboolean
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.
metadataobject
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_secretstring
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_methodstring
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".
descriptionstring
String to add any more information about the charge. This can be used to provide additional context about what the payment is for.
receipt_emailstring
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_urlstring
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_descriptorstring
Text that appears on the customer's statement. This helps the customer identify the transaction on their bank or mobile money statement.
shippingobject
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_referencestring
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.
statusstring · 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_codestring
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_reasonstring
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_atinteger
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_reasonstring · 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
payment_method_detailsobject
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.