Schemas

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).

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

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

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

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.

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.

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

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

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.

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.

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.

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.

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

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

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.

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

Contains information about mobile money payment methods. Supported providers are EcoCash and OneMoney.

Recipient name. This is the name of the person who will receive the shipment. Required if shipping information is provided.

Shipping carrier (e.g., Fedex, DHL, etc.). This helps with tracking shipments and identifying delivery partners.

Tracking number for the shipment. This allows both you and the customer to track the delivery status.

Phone number of the recipient. This is often used by carriers to coordinate delivery details.

The shipping address for the order. This contains all the necessary address information for delivery.

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

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

Contains the monetary value and currency information for the charge.

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.

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.

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.

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.

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.

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".

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

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.

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.

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

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

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.

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.

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.

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.

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.

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.

Type of the returned object.

Array of charge objects.

Pagination metadata

The identifier of the charge to refund. This is the ID of the original charge that you want to refund.

Reason for the refund. This helps with record-keeping and can be useful for tracking why refunds were issued.

This field is optional but recommended for better tracking and reporting.

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the refund 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.

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

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

Contains the monetary value and currency information for the refund.

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

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

ID of the charge that was refunded. This links the refund to the original charge transaction.

Reason for the refund. This is the explanation provided when creating the refund.

Status of the refund. This field indicates where the refund is in the processing lifecycle.

Possible values:

• pending: The refund has been created but not yet processed.
• processing: The refund is in the process of being completed.
• succeeded: The refund completed successfully.
• failed: The refund was attempted but failed.
• cancelled: The refund was cancelled.

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

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

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

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

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

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

Contains information about the refund details. This object provides detailed information about how the refund was processed.

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

Type of the returned object.

Array of refund objects.

Pagination metadata

A list of items the customer is purchasing. Each item in the list represents a product or service that will be displayed to the customer on the checkout page.

At least one line item must be provided.

The mode of the Checkout Session. Currently only supports payment as the mode for one time purchases.

In the future, other modes like subscription or setup might be supported.

The URL to which Payonify should return customers upon successful payment.

After completing the payment, the customer will be redirected to this URL. You can include the session ID in the URL by adding the {CHECKOUT_SESSION_ID} placeholder, which will be replaced with the actual session ID.

Example: https://example.com/success?session_id={CHECKOUT_SESSION_ID}

The URL that will appear on the Checkout page so that if customers need to cancel and go back to your website they can.

If the customer clicks the "back" or "cancel" button on the checkout page, they will be redirected to this URL.

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

All line items in the checkout must use the same currency.

If provided it will be used to prefill customer data on the checkout page. This improves the checkout experience by eliminating the need for the customer to manually enter their email.

A unique string to reference the Checkout Session. This can be anything your system can generate, e.g. Customer ID or Cart ID.

This can be used to reconcile the checkout session with your internal systems, such as an order management system.

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

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

A set of key-value pairs that can be attached to an object. This is useful for storing additional information about the checkout session 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.

Specifies which fields in the response should be expanded. Currently, only line_items is supported for expansion.

When line_items is included in the expand array, the response will include the complete line item details rather than just IDs.

This is used to customize the text on the Checkout page for the submit button. Different types convey different intentions to the customer.

• pay: Standard payment (default)
• donate: Donation to a cause
• book: Booking a service or reservation

A list of the types of payment methods this Checkout Session can accept. If omitted, all active payment methods for the selected currency will be used.

Available payment methods:

• ecocash: Mobile money via Econet EcoCash
• onemoney: Mobile money via NetOne OneMoney
• card: Card payments (Visa, Mastercard) - USD only
• zimswitch: Card payments via Zimswitch

Unique identifier for the checkout session. This ID is used to reference the session in other API calls.

String representing the object's type. Always "checkout_session" for checkout session objects.

The status of the Checkout Session. This indicates the current state of the checkout process.

• open: The checkout session is still active and can be used by the customer.
• complete: The checkout session has been completed successfully.
• expired: The checkout session has expired and can no longer be used.

The mode of the Checkout Session. Currently only supports payment for one-time purchases.

In the future, other modes like subscription or setup might be supported.

Set of key-value pairs attached to the object. This contains the metadata that was provided when creating the checkout session.

This can be used to store additional information about the checkout session for internal purposes.

A three-letter ISO currency code. This is the currency used for all items in the checkout session.

The URL of the Checkout Session that the customer should be redirected to.

After creating a checkout session, redirect your customer to this URL to complete the payment on the Payonify hosted checkout page.

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

This helps distinguish between test transactions and real payments.

A list of the types of payment methods this Checkout Session can accept.

This array contains all the payment methods that will be available to the customer on the checkout page.

Available payment methods:

• ecocash: Mobile money via Econet EcoCash
• onemoney: Mobile money via NetOne OneMoney
• card: Card payments (Visa, Mastercard) - USD only, checkout only
• zimswitch: Card payments via Zimswitch - checkout only

Note: Card payments (card and zimswitch) are only available through Checkout Sessions and cannot be used with charges.

A client secret for the charge associated with this checkout session.

This secret is used when implementing client-side confirmation of payments. It should be kept secure and only used in secure contexts.

Total of all items after discounts and taxes.

This is the final amount that will be charged to the customer, represented in the smallest unit of the currency (e.g., cents).

A unique string to reference the Checkout Session. This is the same ID that was provided when creating the session, or an auto-generated one if none was provided.

This can be used to reconcile the checkout session with your internal systems.

The time in seconds (Unix epoch) at which the Checkout Session will expire.

By default, checkout sessions expire after 24 hours. Once expired, they can no longer be used to complete a payment.

The Charge reference associated with this Checkout Session.

When a checkout session is created, a charge is also created in a pending state. This is the ID of that charge, which can be used to retrieve details or perform operations on the charge if needed.

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

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

Total of all items before any discounts or taxes.

This is the sum of (unit_amount * quantity) for all line items, represented in the smallest unit of the currency (e.g., cents).

The URL to redirect customers who cancel checkout.

If the customer clicks the "back" or "cancel" button on the checkout page, they will be redirected to this URL.

Customer email address. If provided when creating the checkout session, this will be pre-filled on the checkout page.

This improves the checkout experience by eliminating the need for the customer to manually enter their email.

The payment status of the Checkout Session. This indicates the current state of the payment process.

• requires_payment_method: The customer has not yet provided a payment method.
• pending: The payment is being processed.
• succeeded: The payment completed successfully.
• failed: The payment attempt failed.
• cancelled: The payment was cancelled.

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

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

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

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

The URL to redirect customers upon successful payment.

After completing the payment, the customer will be redirected to this URL.

Describes the type of transaction being performed. This affects the text displayed on the submit button on the checkout page.

• pay: Standard payment (default)
• donate: Donation to a cause
• book: Booking a service or reservation

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.

A list of items the customer is purchasing. Each item in the list represents a product or service that will be displayed to the customer on the checkout page.

This field is only included in the response if line_items was included in the expand array when creating or retrieving the checkout session.

Type of the returned object.

Array of checkout session objects.

Pagination metadata

Mobile money destination details. Contains provider-specific objects.

The destination for the payout funds. The destination is structured to support multiple destination types. Currently, EcoCash mobile money is the available destination, with more options (e.g., OneMoney, bank transfer) coming soon.

Whether the recipient account is valid and can receive payouts.

Details about the validated recipient. Only present when valid is true.

A positive integer representing the payout amount in the smallest currency unit (e.g. 100 cents = $1.00).

The minimum amount is 100 (e.g., $1.00).

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

The destination for the payout funds. The destination is structured to support multiple destination types. Currently, EcoCash mobile money is the available destination, with more options (e.g., OneMoney, bank transfer) coming soon.

An optional description for the payout. This can be used for internal reference or record-keeping.

Maximum 150 characters.

A set of key-value pairs for storing additional information about the payout.

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

Unique identifier for the payout object. Payout IDs have the prefix po_.

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

Contains the monetary value and currency information for the payout.

Has the value true if the object exists in live mode or false if in test mode.

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

The status of the payout.

Possible values:

• pending: The payout has been created and is being processed.
• paid: The payout completed successfully and funds have been delivered.
• failed: The payout failed to process.

Description of the payout, if one was provided at creation time.

A set of key-value pairs attached to the payout.

Contains information about the payout destination. The structure depends on the destination type used.

Error code for a failed payout. This field will be null if the payout has not failed.

A human-readable message providing more details about why the payout failed. This field will be null if the payout has not failed.

Type of the returned object.

Array of payout objects.

Pagination metadata

Contains detailed information about the error.