Payouts

Move money out of a gift card. Pick one destination per request:

Business — send to another Chapa merchant (merchant_id)
Another card — transfer to another gift card (destination_card_number)
Bank or wallet — withdraw to a bank account (bank_slug, account_number, account_name)

Only send fields for one payout type. Mixing merchant_id and bank_slug in the same request will fail.

Endpoint (all payout types)

POST https://api.chapa.link/card/payouts
Authorization: Bearer {{API_KEY}}
Content-Type: application/json

Payout to Business

Send funds from a gift card to another Chapa merchant. Optionally set who pays the service fee with charge_payer.

Field	Required	Description
`card_number`	Yes	Source gift card to debit
`merchant_id`	Yes	Destination Chapa merchant ID
`amount`	Yes	Amount to send (minor units)
`charge_payer`	No	Who pays the service fee: `business` (default) or `customer`

business — the source card is debited amount; the merchant receives amount - service_fee
customer — the source card is debited amount + service_fee; the merchant receives the full amount

{
  "card_number": "7878064900",
  "merchant_id": "912121313",
  "amount": 100,
  "charge_payer": "business"
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "chapa_reference": "APh81527081a",
    "status": "SUCCESS",
    "updated_at": "2026-06-15T12:38:01.651814865Z",
    "created_at": "2026-06-15T12:38:01.651814865Z"
  }
}

Error Responses

Status	Message	When
`400`	Validation error	Missing required fields or multiple destination types sent
`400`	Invalid payout request	More than one of `merchant_id`, `destination_card_number`, or bank fields provided
`400`	Invalid charge payer	`charge_payer` is not `business` or `customer`
`400`	Amount is too small to cover the service fee	`charge_payer` is `business` and `amount` does not cover the fee
`404`	Gift card not found	Source `card_number` does not exist on your account
`400`	Gift card disabled	Source card is not active
`400`	Insufficient balance	Source card does not have enough funds

{
  "status": "error",
  "message": "Invalid payout request. Provide exactly one of merchant_id (B2B), destination_card_number (card-to-card), or bank account details (bank withdrawal)",
  "error": "Provide exactly one of merchant_id (B2B), destination_card_number (card-to-card), or bank account details (bank withdrawal)"
}

{
  "status": "error",
  "message": "Insufficient balance",
  "error": "Insufficient balance"
}

Payout to Another Card

Instant transfer from your card to any active gift card with a matching currency. The destination card does not need to belong to your business.

Use charge_payer to choose whether the sender or receiver pays the service fee. Defaults to the sender card.

Field	Required	Description
`card_number`	Yes	Source (sender) gift card to debit
`destination_card_number`	Yes	Destination (receiver) gift card to credit
`amount`	Yes	Amount to transfer (minor units)
`charge_payer`	No	Who pays the service fee: `sender` (default) or `receiver`

sender — the source card is debited amount + service_fee; the destination receives the full amount
receiver — the source card is debited amount; the destination receives amount - service_fee

{
  "card_number": "7878064900",
  "amount": 100,
  "destination_card_number": "8787064900",
  "charge_payer": "sender"
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "initiator_reference": "GCy79131114X",
    "source_card_number": "7878064900",
    "destination_card_number": "8787064900",
    "amount": 100,
    "service_fee": 0,
    "charge_payer": "sender",
    "currency": "ETB"
  }
}

Error Responses

Status	Message	When
`400`	Same card	Source and destination `card_number` are identical
`400`	Invalid charge payer	`charge_payer` is not `sender` or `receiver`
`400`	Amount is too small to cover the service fee	`charge_payer` is `receiver` and `amount` does not cover the fee
`404`	Destination card not found	No active gift card exists for `destination_card_number`
`400`	Destination card disabled	Destination card is not active
`400`	Currency mismatch	Source and destination cards use different currencies
`400`	Insufficient balance	Source card does not have enough funds

{
  "status": "error",
  "message": "Currency mismatch. Source and destination cards must share the same currency",
  "error": "Source and destination cards must share the same currency"
}

{
  "status": "error",
  "message": "Invalid charge payer",
  "error": "charge_payer must be either sender or receiver for card-to-card payouts"
}

Payout to Bank

See the Chapa bank list for valid bank_slug values.

Optionally set who pays the service fee with charge_payer (same options as business payouts).

Field	Required	Description
`card_number`	Yes	Source gift card to debit
`amount`	Yes	Amount to withdraw (minor units)
`bank_slug`	Yes	Destination bank or wallet slug
`account_number`	Yes	Destination account number
`account_name`	Yes	Destination account holder name
`charge_payer`	No	Who pays the service fee: `business` (default) or `customer`

business — the source card is debited amount; the bank account receives amount - service_fee
customer — the source card is debited amount + service_fee; the bank account receives the full amount

{
  "card_number": "5610764625",
  "amount": 100,
  "bank_slug": "telebirr",
  "account_number": "0926760003",
  "account_name": "Abebe Bikila",
  "charge_payer": "business"
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "chapa_reference": "CP17791313067814",
    "status": "PENDING"
  }
}

Bank payouts may start as PENDING while the transfer processes.

Error Responses

Status	Message	When
`400`	Invalid payout request	`bank_slug`, `account_number`, and `account_name` must all be provided together
`400`	Invalid charge payer	`charge_payer` is not `business` or `customer`
`400`	Amount is too small to cover the service fee	`charge_payer` is `business` and `amount` does not cover the fee
`400`	Gift card disabled	Source card is not active
`400`	Insufficient balance	Source card does not have enough funds
`400`–`502`	Payout request failed	Invalid bank slug, account, or upstream payout error

{
  "status": "error",
  "message": "Invalid payout request. bank_slug, account_number, and account_name are all required for bank withdrawal",
  "error": "bank_slug, account_number, and account_name are all required for bank withdrawal"
}

List Payouts

Returns paginated payout records for your business. Use page and limit to page through results. Each item includes mode (live or test) matching your API key environment.

GET https://api.chapa.link/card/payouts?page=1&limit=15
Authorization: Bearer {{API_KEY}}

Query	Default	Max	Description
`page`	`1`	—	Page number (1-based)
`limit`	`15`	`100`	Number of records per page
`offset`	—	—	Optional alternative to `page` (0-based skip)

List item fields

Field	When present	Description
`payout_type`	Always	`card_to_card`, `bank`, or `b2b`
`status`	Always	`pending`, `success`, or `failed`
`currency`	Always	Card currency
`amount`	Always	Amount in minor units
`service_fee`	Always	Fee charged on the transaction
`initiator_reference`	Card-to-card	Reference from `POST /card/payouts`
`chapa_reference`	Bank or B2B	Reference from `POST /card/payouts`
`source_card_number`	Always	Card debited
`destination_card_number`	Card-to-card	Card credited
`merchant_id`	B2B	Destination Chapa merchant ID
`mode`	Always	`live` or `test`
`created_at`	Always	When the payout was created
`updated_at`	Always	When the payout was last updated

Only the reference field that matches payout_type is included (initiator_reference or chapa_reference, not both).

Check Payout Status

GET https://api.chapa.link/card/payout/GCy79131114X/status
Authorization: Bearer {{API_KEY}}

Use initiator_reference (card-to-card), chapa_reference (bank/business), or the reference returned when you started the payout.

Success Response

{
  "status": "success",
  "message": "Payout status fetched successfully",
  "data": {
    "reference": "GCy79131114X",
    "chapa_ref": "CHFghskey123",
    "amount": 100,
    "service_fee": 0,
    "currency": "ETB",
    "status": "success",
    "created_at": "2026-06-21T12:00:00Z",
    "completed_at": "2026-06-21T12:00:00Z"
  }
}

Error Responses

Status	Message	When
`400`	Invalid request	`reference` path parameter is missing
`404`	Payout not found	Reference does not exist or does not belong to your business

{
  "status": "error",
  "message": "Payout not found",
  "error": "Payout not found"
}

You can use the standard Chapa withdrawal flow to send funds from your Chapa business account to a Gift Card Ledger. This is effectively the same flow as a normal Chapa payout—refer to the Chapa payout documentation for more details.

To fund a gift card, simply use the "link" bank slug and set the account_number to the gift card number you wish to top up.

{
  "amount": 500, // amount to top up
  "bank_slug": "link", // must be "link" for gift card payout
  "account_number": "GCARD123456789", // target gift card number
  "account_name": "Gift Card Name" // can be reference name
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "chapa_reference": "CP17815960544446",
    "status": "PENDING",
    "created_at": "2026-06-16T07:47:34.58741Z",
    "updated_at": "2026-06-16T07:47:34.587421Z"
  }
}

Error Response

{
  "status": "error",
  "message": "Invalid bank slug",
  "error": "Invalid bank slug"
}

This will start a withdrawal from your business balance to the specified gift card, following Chapa's normal payout status and flow. You can track the payout via status endpoints as usual.

Note: Make sure your Chapa business account has enough funds to perform the payout.

Tips

Make sure the source card has enough available_amount
Card-to-card payouts need the same currency on both cards; the destination can be any active gift card
For card-to-card, use charge_payer: sender (default) or receiver; for business and bank payouts use business (default) or customer
Use GET /card/payouts to page through payout history for your business
Use webhooks for bank payouts in production

Payouts

Move money out of a gift card. Pick one destination per request:

Business — send to another Chapa merchant (merchant_id)
Another card — transfer to another gift card (destination_card_number)
Bank or wallet — withdraw to a bank account (bank_slug, account_number, account_name)

Only send fields for one payout type. Mixing merchant_id and bank_slug in the same request will fail.

Variables

{{API_KEY}}: your API key

Endpoint (all payout types)

POST https://api.chapa.link/card/payouts
Authorization: Bearer {{API_KEY}}
Content-Type: application/json

Payout to Business

Send funds from a gift card to another Chapa merchant. Optionally set who pays the service fee with charge_payer.

Field	Required	Description
`card_number`	Yes	Source gift card to debit
`merchant_id`	Yes	Destination Chapa merchant ID
`amount`	Yes	Amount to send (minor units)
`charge_payer`	No	Who pays the service fee: `business` (default) or `customer`

business — the source card is debited amount; the merchant receives amount - service_fee
customer — the source card is debited amount + service_fee; the merchant receives the full amount

{
  "card_number": "7878064900",
  "merchant_id": "912121313",
  "amount": 100,
  "charge_payer": "business"
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "chapa_reference": "APh81527081a",
    "status": "SUCCESS",
    "updated_at": "2026-06-15T12:38:01.651814865Z",
    "created_at": "2026-06-15T12:38:01.651814865Z"
  }
}

Error Responses

Status	Message	When
`400`	Validation error	Missing required fields or multiple destination types sent
`400`	Invalid payout request	More than one of `merchant_id`, `destination_card_number`, or bank fields provided
`400`	Invalid charge payer	`charge_payer` is not `business` or `customer`
`400`	Amount is too small to cover the service fee	`charge_payer` is `business` and `amount` does not cover the fee
`404`	Gift card not found	Source `card_number` does not exist on your account
`400`	Gift card disabled	Source card is not active
`400`	Insufficient balance	Source card does not have enough funds

{
  "status": "error",
  "message": "Invalid payout request. Provide exactly one of merchant_id (B2B), destination_card_number (card-to-card), or bank account details (bank withdrawal)",
  "error": "Provide exactly one of merchant_id (B2B), destination_card_number (card-to-card), or bank account details (bank withdrawal)"
}

{
  "status": "error",
  "message": "Insufficient balance",
  "error": "Insufficient balance"
}

Payout to Another Card

Instant transfer from your card to any active gift card with a matching currency. The destination card does not need to belong to your business.

Use charge_payer to choose whether the sender or receiver pays the service fee. Defaults to the sender card.

Field	Required	Description
`card_number`	Yes	Source (sender) gift card to debit
`destination_card_number`	Yes	Destination (receiver) gift card to credit
`amount`	Yes	Amount to transfer (minor units)
`charge_payer`	No	Who pays the service fee: `sender` (default) or `receiver`

sender — the source card is debited amount + service_fee; the destination receives the full amount
receiver — the source card is debited amount; the destination receives amount - service_fee

{
  "card_number": "7878064900",
  "amount": 100,
  "destination_card_number": "8787064900",
  "charge_payer": "sender"
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "initiator_reference": "GCy79131114X",
    "source_card_number": "7878064900",
    "destination_card_number": "8787064900",
    "amount": 100,
    "service_fee": 0,
    "charge_payer": "sender",
    "currency": "ETB"
  }
}

Error Responses

Status	Message	When
`400`	Same card	Source and destination `card_number` are identical
`400`	Invalid charge payer	`charge_payer` is not `sender` or `receiver`
`400`	Amount is too small to cover the service fee	`charge_payer` is `receiver` and `amount` does not cover the fee
`404`	Destination card not found	No active gift card exists for `destination_card_number`
`400`	Destination card disabled	Destination card is not active
`400`	Currency mismatch	Source and destination cards use different currencies
`400`	Insufficient balance	Source card does not have enough funds

{
  "status": "error",
  "message": "Currency mismatch. Source and destination cards must share the same currency",
  "error": "Source and destination cards must share the same currency"
}

{
  "status": "error",
  "message": "Invalid charge payer",
  "error": "charge_payer must be either sender or receiver for card-to-card payouts"
}

Payout to Bank

See the Chapa bank list for valid bank_slug values.

Optionally set who pays the service fee with charge_payer (same options as business payouts).

Field	Required	Description
`card_number`	Yes	Source gift card to debit
`amount`	Yes	Amount to withdraw (minor units)
`bank_slug`	Yes	Destination bank or wallet slug
`account_number`	Yes	Destination account number
`account_name`	Yes	Destination account holder name
`charge_payer`	No	Who pays the service fee: `business` (default) or `customer`

business — the source card is debited amount; the bank account receives amount - service_fee
customer — the source card is debited amount + service_fee; the bank account receives the full amount

{
  "card_number": "5610764625",
  "amount": 100,
  "bank_slug": "telebirr",
  "account_number": "0926760003",
  "account_name": "Abebe Bikila",
  "charge_payer": "business"
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "chapa_reference": "CP17791313067814",
    "status": "PENDING"
  }
}

Bank payouts may start as PENDING while the transfer processes.

Error Responses

Status	Message	When
`400`	Invalid payout request	`bank_slug`, `account_number`, and `account_name` must all be provided together
`400`	Invalid charge payer	`charge_payer` is not `business` or `customer`
`400`	Amount is too small to cover the service fee	`charge_payer` is `business` and `amount` does not cover the fee
`400`	Gift card disabled	Source card is not active
`400`	Insufficient balance	Source card does not have enough funds
`400`–`502`	Payout request failed	Invalid bank slug, account, or upstream payout error

{
  "status": "error",
  "message": "Invalid payout request. bank_slug, account_number, and account_name are all required for bank withdrawal",
  "error": "bank_slug, account_number, and account_name are all required for bank withdrawal"
}

List Payouts

Returns paginated payout records for your business. Use page and limit to page through results. Each item includes mode (live or test) matching your API key environment.

GET https://api.chapa.link/card/payouts?page=1&limit=15
Authorization: Bearer {{API_KEY}}

Query	Default	Max	Description
`page`	`1`	—	Page number (1-based)
`limit`	`15`	`100`	Number of records per page
`offset`	—	—	Optional alternative to `page` (0-based skip)

Success Response

{
  "status": "success",
  "message": "Payouts fetched successfully",
  "data": {
    "items": [
      {
        "payout_type": "card_to_card",
        "status": "success",
        "currency": "ETB",
        "amount": 100,
        "service_fee": 0,
        "initiator_reference": "GCy79131114X",
        "source_card_number": "7878064900",
        "destination_card_number": "8787064900",
        "mode": "live",
        "created_at": "2026-06-21T12:00:00Z",
        "updated_at": "2026-06-21T12:00:00Z"
      },
      {
        "payout_type": "b2b",
        "status": "success",
        "currency": "ETB",
        "amount": 250,
        "service_fee": 0,
        "chapa_reference": "CP17815960544447",
        "source_card_number": "5610764625",
        "merchant_id": "912121313",
        "mode": "live",
        "created_at": "2026-06-21T11:45:00Z",
        "updated_at": "2026-06-21T11:45:00Z"
      },
      {
        "payout_type": "bank",
        "status": "pending",
        "currency": "ETB",
        "amount": 500,
        "service_fee": 0,
        "chapa_reference": "CP17815960544446",
        "source_card_number": "5610764625",
        "mode": "live",
        "created_at": "2026-06-21T11:30:00Z",
        "updated_at": "2026-06-21T11:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 15,
    "pages": 3
  }
}

Results are ordered by newest first.

List item fields

Field	When present	Description
`payout_type`	Always	`card_to_card`, `bank`, or `b2b`
`status`	Always	`pending`, `success`, or `failed`
`currency`	Always	Card currency
`amount`	Always	Amount in minor units
`service_fee`	Always	Fee charged on the transaction
`initiator_reference`	Card-to-card	Reference from `POST /card/payouts`
`chapa_reference`	Bank or B2B	Reference from `POST /card/payouts`
`source_card_number`	Always	Card debited
`destination_card_number`	Card-to-card	Card credited
`merchant_id`	B2B	Destination Chapa merchant ID
`mode`	Always	`live` or `test`
`created_at`	Always	When the payout was created
`updated_at`	Always	When the payout was last updated

Only the reference field that matches payout_type is included (initiator_reference or chapa_reference, not both).

Check Payout Status

GET https://api.chapa.link/card/payout/GCy79131114X/status
Authorization: Bearer {{API_KEY}}

Use initiator_reference (card-to-card), chapa_reference (bank/business), or the reference returned when you started the payout.

Success Response

{
  "status": "success",
  "message": "Payout status fetched successfully",
  "data": {
    "reference": "GCy79131114X",
    "chapa_ref": "CHFghskey123",
    "amount": 100,
    "service_fee": 0,
    "currency": "ETB",
    "status": "success",
    "created_at": "2026-06-21T12:00:00Z",
    "completed_at": "2026-06-21T12:00:00Z"
  }
}

Error Responses

Status	Message	When
`400`	Invalid request	`reference` path parameter is missing
`404`	Payout not found	Reference does not exist or does not belong to your business

{
  "status": "error",
  "message": "Payout not found",
  "error": "Payout not found"
}

Gift Card - Ledger Payout

To fund a gift card, simply use the "link" bank slug and set the account_number to the gift card number you wish to top up.

{
  "amount": 500, // amount to top up
  "bank_slug": "link", // must be "link" for gift card payout
  "account_number": "GCARD123456789", // target gift card number
  "account_name": "Gift Card Name" // can be reference name
}

Success Response

{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "chapa_reference": "CP17815960544446",
    "status": "PENDING",
    "created_at": "2026-06-16T07:47:34.58741Z",
    "updated_at": "2026-06-16T07:47:34.587421Z"
  }
}

Error Response

{
  "status": "error",
  "message": "Invalid bank slug",
  "error": "Invalid bank slug"
}

This will start a withdrawal from your business balance to the specified gift card, following Chapa's normal payout status and flow. You can track the payout via status endpoints as usual.

Note: Make sure your Chapa business account has enough funds to perform the payout.

Tips

Make sure the source card has enough available_amount
Card-to-card payouts need the same currency on both cards; the destination can be any active gift card
For card-to-card, use charge_payer: sender (default) or receiver; for business and bank payouts use business (default) or customer
Use GET /card/payouts to page through payout history for your business
Use webhooks for bank payouts in production

On this page

On this page