Chapa Developer Documentation

Accept payments using a simple HTML form that redirects customers to Chapa's hosted payment page

Our HTML checkout option is done entirely in HTML. You create a regular HTML form containing the payment details. When the customer submits the form, they'll be redirected to our payment page where they can complete the payment.

An Example

Here's an example of how you'd implement HTML checkout:

<form method="POST" action="https://api.chapa.co/v1/hosted/pay">
  <input type="hidden" name="public_key" value="YOUR_PUBLIC_API_KEY" />
  <input type="hidden" name="tx_ref" value="negade-tx-12345678sss9" />
  <input type="hidden" name="amount" value="10" />
  <input type="hidden" name="currency" value="ETB" />
  <input type="hidden" name="email" value="israel@negade.et" />
  <input type="hidden" name="first_name" value="Israel" />
  <input type="hidden" name="last_name" value="Goytom" />
  <input type="hidden" name="title" value="Let us do this" />
  <input type="hidden" name="description" value="Paying with Confidence with cha" />
  <input type="hidden" name="logo" value="https://chapa.link/asset/images/chapa_swirl.svg" />
  <input type="hidden" name="callback_url" value="https://example.com/callbackurl" />
  <input type="hidden" name="return_url" value="https://example.com/returnurl" />
  <input type="hidden" name="meta[title]" value="test" />
  <button type="submit">Pay Now</button>
</form>

Walkthrough

Let's take a closer look at what this code is doing.

Form Setup

First, we create a regular HTML form. The form must have the method as POST, and the action pointing to Chapa's hosted checkout page.

<form method="POST" action="https://api.chapa.co/v1/hosted/pay">

Public API Key

Second up is setting your public API key. You can get your public API key from your dashboard after signing up. Checkout Quick Start on how you can get it.

<input type="hidden" name="public_key" value="YOUR_PUBLIC_API_KEY" />

Payment Button

Next up is the payment button. This is the button the customer clicks after they've reviewed their order and are ready to pay you. Make sure it's inside the form and set to type="submit" so the form submits when it's clicked.

<form method="POST" action="https://api.chapa.co/v1/hosted/pay">
  <button type="submit">Pay Now</button>
</form>

Form Fields

Finally, we add hidden input fields to the form containing the payment options. These payment options are the same values used in the Standard flows, converted into form fields. Object fields are referenced with square brackets.

Field	Required	Description
`public_key`	Yes	Your public API key
`tx_ref`	Yes	A unique reference given to each transaction
`amount`	Yes	The amount you will be charging your customer
`currency`	Yes	Currency for charges (ETB or USD)
`email`	No	A customer's email address
`first_name`	No	A customer's first name
`last_name`	No	A customer's last name
`title`	No	Custom title for the payment page
`description`	No	Description of the payment
`logo`	No	URL to your logo image
`callback_url`	No	URL that receives payment status after payment
`return_url`	No	Web address to redirect the user after payment
`meta[title]`	No	Additional metadata (object fields use brackets)

On your server, you should handle the redirect and always verify the final state of the transaction.

Transaction verification should always be done on the server, as it makes use of your secret key, which should never be exposed publicly.

What if the Payment Fails?

If the payment attempt fails (for instance, due to insufficient funds), you don't need to do anything. We'll keep the payment page open, so the customer can try again until the payment succeeds or they choose to cancel.

Next Steps

Verify Transaction - Always verify payments on your server
Webhooks - Set up real-time notifications
Error Codes - Handle errors gracefully

HTML Checkout