Gift Cards

Gift cards are the core resource in Link App. Create one for a customer, store the returned card_number, and use that card number later when initiating payments or payouts.

Create Gift Card

Creates a gift card for a customer identified by phone number. The API returns the card details.

Endpoint

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

Request Body

{
  "first_name": "Abebe",
  "last_name": "Bikila",
  "phone_number": "+251960724272",
  "currency": "ETB"
}

Field	Required	Description
`phone_number`	Yes	Customer phone, e.g. `+251...`
`currency`	Yes	`ETB`, `USD`, `DJF`, or `UGX`
`first_name`	Sometimes	Required if this phone number is new to Link
`last_name`	No	Customer last name

Each customer can only have one card per currency on your account. If a card already exists, you'll get an error — use the existing card_number instead.

Error Responses

Status	Message	When
`400`	Validation error	Missing or invalid fields (e.g. unsupported `currency`)
`400`	Invalid phone number	Phone number is not in a valid international format
`404`	User not found	Phone number is new and `first_name` was not provided
`409`	Gift card already exists	Customer already has a card for this currency on your account

{
  "status": "error",
  "message": "Validation error",
  "error": {
    "currency": "Currency must be one of: ETB, USD, DJF, UGX"
  }
}

{
  "status": "error",
  "message": "Gift card already exists. A gift card already exists for this user, currency, and business",
  "error": "A gift card already exists for this user, currency, and business"
}

List Gift Cards

This returns gift cards created under that business for it's customers.

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

Query	Description
`page`	Page number (default `1`)
`limit`	Items per page (default `15`)
`phone_number`	Filter by phone number(`9...`)

No country code when filtering gift cards with phone number.

Success Response

{
  "status": "success",
  "message": "Gift cards fetched successfully",
  "data": {
    "items": [
      {
        "ref_id": "GCP81523171v",
        "name": "Abebe Bikila",
        "card_number": "9285944660",
        "currency": "ETB",
        "status": 1,
        "last_four": "4660",
        "is_scoped": 1,
        "business_id": 467736,
        "available_amount": 1000,
        "created_at": "2026-06-15T03:52:25.663456Z",
        "updated_at": "2026-06-15T03:52:25.663456Z"
      },
      {
        "ref_id": "GCP81523171v",
        "name": "Derartu Tulu",
        "card_number": "911123456",
        "currency": "ETB",
        "status": 1,
        "last_four": "4660",
        "is_scoped": 1,
        "business_id": 467736,
        "available_amount": 0,
        "created_at": "2026-06-15T11:32:51.740639Z",
        "updated_at": "2026-06-15T11:32:51.740639Z"
      },
    ],
    "page": 1,
    "pages": 1,
    "size": 15,
    "total": 2
  }
}

Error Responses

Status	Message	When
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key is inactive or not set up for gift cards

Gift Card Detail

returns one gift card identified by its card number

GET https://api.chapa.link/card/9580246965
Authorization: Bearer {{API_KEY}}

{
  "status": "success",
  "message": "Gift card fetched successfully",
  "data": {
    "ref_id": "GCP81523171v",
    "name": "Abebe Bikila",
    "card_number": "9285944660",
    "currency": "ETB",
    "status": 1,
    "last_four": "4660",
    "is_scoped": 1,
    "business_id": 467736,
    "available_amount": 1000,
    "created_at": "2026-06-15T03:52:25.663456Z",
    "updated_at": "2026-06-15T03:52:25.663456Z"
  }
}

Error Responses

Status	Message	When
`400`	Invalid card number	`card_number` path parameter is missing
`404`	Gift card not found	Card does not exist or does not belong to your business

{
  "status": "error",
  "message": "Gift card not found. The provided gift card does not exist",
  "error": "The provided gift card does not exist"
}

Enable or Disable a Card

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

{
  "status": "disable"
}

Successful Response

{
  "status": "success",
  "message": "Gift card disabled successfully",
  "data": {
    "ref_id": "GCP81523171v",
    "name": "Abebe Bikila",
    "card_number": "9285944660",
    "currency": "ETB",
    "status": 3,
    "last_four": "4660",
    "is_scoped": 1,
    "business_id": 467736,
    "available_amount": 0,
    "created_at": "2026-06-15T11:32:51.740639Z",
    "updated_at": "2026-06-15T11:38:53.778477Z"
  }
}

Use "enable" to turn the card back on. Disabled cards cannot be used for payments or payouts.

{
  "status": "enable"
}

Successful Response

{
  "status": "success",
  "message": "Gift card enabled successfully",
  "data": {
    "ref_id": "GCP81523171v",
    "name": "Abebe Bikila",
    "card_number": "9285944660",
    "currency": "ETB",
    "status": 1,
    "last_four": "4660",
    "is_scoped": 1,
    "business_id": 467736,
    "available_amount": 0,
    "created_at": "2026-06-15T11:32:51.740639Z",
    "updated_at": "2026-06-15T11:38:53.778477Z"
  }
}

Error Responses

Status	Message	When
`400`	Validation error	`status` is missing or not `enable` / `disable`
`400`	Invalid card number	`card_number` path parameter is missing
`404`	Gift card not found	Card does not exist or does not belong to your business
`403`	Cannot enable	Card was disabled by another actor and only they can re-enable it
`409`	Already disabled	Card is already disabled

{
  "status": "error",
  "message": "Validation error",
  "error": {
    "status": "Status must be one of: enable, disable"
  }
}

{
  "status": "error",
  "message": "Cannot enable. Only merchant may re-enable this card",
  "error": "Only merchant may re-enable this card"
}

Cancels a gift card identified by its card number. The card must belong to your business. After cancellation, the card no longer appears in list or detail responses and cannot be used for payments or payouts.

You can create a new card for the same customer and currency after cancelling the previous one.

Endpoint

DELETE https://api.chapa.link/card/9285944660
Authorization: Bearer {{API_KEY}}

No request body.

Success Response

{
  "status": "success",
  "message": "Gift card cancelled successfully",
  "data": null
}

Error Responses

Status	Message	When
`400`	Invalid card number	`card_number` path parameter is missing
`404`	Gift card not found	Card does not exist or does not belong to your business

{
  "status": "error",
  "message": "Gift card not found. The provided gift card does not exist",
  "error": "The provided gift card does not exist"
}

Tips

Always save card_number after creation
Use international format for phone numbers
Check available_amount before starting a payout

Gift Cards

Gift cards are the core resource in Link App. Create one for a customer, store the returned card_number, and use that card number later when initiating payments or payouts.

Variables

{{API_KEY}}: your API key

Create Gift Card

Creates a gift card for a customer identified by phone number. The API returns the card details.

Endpoint

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

Request Body

{
  "first_name": "Abebe",
  "last_name": "Bikila",
  "phone_number": "+251960724272",
  "currency": "ETB"
}

Field	Required	Description
`phone_number`	Yes	Customer phone, e.g. `+251...`
`currency`	Yes	`ETB`, `USD`, `DJF`, or `UGX`
`first_name`	Sometimes	Required if this phone number is new to Link
`last_name`	No	Customer last name

Each customer can only have one card per currency on your account. If a card already exists, you'll get an error — use the existing card_number instead.

Success Response

{
  "status": "success",
  "message": "Gift card created successfully",
  "data": {
    "ref_id": "GCP81523171v",
    "name": "Abebe Bikila",
    "card_number": "9285944660",
    "currency": "ETB",
    "status": 1,
    "last_four": "4660",
    "is_scoped": 1,
    "business_id": 467736,
    "available_amount": 0,
    "created_at": "2026-06-15T11:32:51.740639545Z",
    "updated_at": "2026-06-15T11:32:51.740639545Z"
  }
}

status: 1 means the card is active.

Error Responses

Status	Message	When
`400`	Validation error	Missing or invalid fields (e.g. unsupported `currency`)
`400`	Invalid phone number	Phone number is not in a valid international format
`404`	User not found	Phone number is new and `first_name` was not provided
`409`	Gift card already exists	Customer already has a card for this currency on your account

{
  "status": "error",
  "message": "Validation error",
  "error": {
    "currency": "Currency must be one of: ETB, USD, DJF, UGX"
  }
}

{
  "status": "error",
  "message": "Gift card already exists. A gift card already exists for this user, currency, and business",
  "error": "A gift card already exists for this user, currency, and business"
}

List Gift Cards

This returns gift cards created under that business for it's customers.

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

Query	Description
`page`	Page number (default `1`)
`limit`	Items per page (default `15`)
`phone_number`	Filter by phone number(`9...`)

No country code when filtering gift cards with phone number.

Success Response

{
  "status": "success",
  "message": "Gift cards fetched successfully",
  "data": {
    "items": [
      {
        "ref_id": "GCP81523171v",
        "name": "Abebe Bikila",
        "card_number": "9285944660",
        "currency": "ETB",
        "status": 1,
        "last_four": "4660",
        "is_scoped": 1,
        "business_id": 467736,
        "available_amount": 1000,
        "created_at": "2026-06-15T03:52:25.663456Z",
        "updated_at": "2026-06-15T03:52:25.663456Z"
      },
      {
        "ref_id": "GCP81523171v",
        "name": "Derartu Tulu",
        "card_number": "911123456",
        "currency": "ETB",
        "status": 1,
        "last_four": "4660",
        "is_scoped": 1,
        "business_id": 467736,
        "available_amount": 0,
        "created_at": "2026-06-15T11:32:51.740639Z",
        "updated_at": "2026-06-15T11:32:51.740639Z"
      },
    ],
    "page": 1,
    "pages": 1,
    "size": 15,
    "total": 2
  }
}

Error Responses

Status	Message	When
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key is inactive or not set up for gift cards

Gift Card Detail

returns one gift card identified by its card number

GET https://api.chapa.link/card/9580246965
Authorization: Bearer {{API_KEY}}

{
  "status": "success",
  "message": "Gift card fetched successfully",
  "data": {
    "ref_id": "GCP81523171v",
    "name": "Abebe Bikila",
    "card_number": "9285944660",
    "currency": "ETB",
    "status": 1,
    "last_four": "4660",
    "is_scoped": 1,
    "business_id": 467736,
    "available_amount": 1000,
    "created_at": "2026-06-15T03:52:25.663456Z",
    "updated_at": "2026-06-15T03:52:25.663456Z"
  }
}

Error Responses

Status	Message	When
`400`	Invalid card number	`card_number` path parameter is missing
`404`	Gift card not found	Card does not exist or does not belong to your business

{
  "status": "error",
  "message": "Gift card not found. The provided gift card does not exist",
  "error": "The provided gift card does not exist"
}

Enable or Disable a Card

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

{
  "status": "disable"
}

Successful Response

{
  "status": "success",
  "message": "Gift card disabled successfully",
  "data": {
    "ref_id": "GCP81523171v",
    "name": "Abebe Bikila",
    "card_number": "9285944660",
    "currency": "ETB",
    "status": 3,
    "last_four": "4660",
    "is_scoped": 1,
    "business_id": 467736,
    "available_amount": 0,
    "created_at": "2026-06-15T11:32:51.740639Z",
    "updated_at": "2026-06-15T11:38:53.778477Z"
  }
}

Use "enable" to turn the card back on. Disabled cards cannot be used for payments or payouts.

{
  "status": "enable"
}

Successful Response

{
  "status": "success",
  "message": "Gift card enabled successfully",
  "data": {
    "ref_id": "GCP81523171v",
    "name": "Abebe Bikila",
    "card_number": "9285944660",
    "currency": "ETB",
    "status": 1,
    "last_four": "4660",
    "is_scoped": 1,
    "business_id": 467736,
    "available_amount": 0,
    "created_at": "2026-06-15T11:32:51.740639Z",
    "updated_at": "2026-06-15T11:38:53.778477Z"
  }
}

Error Responses

Status	Message	When
`400`	Validation error	`status` is missing or not `enable` / `disable`
`400`	Invalid card number	`card_number` path parameter is missing
`404`	Gift card not found	Card does not exist or does not belong to your business
`403`	Cannot enable	Card was disabled by another actor and only they can re-enable it
`409`	Already disabled	Card is already disabled

{
  "status": "error",
  "message": "Validation error",
  "error": {
    "status": "Status must be one of: enable, disable"
  }
}

{
  "status": "error",
  "message": "Cannot enable. Only merchant may re-enable this card",
  "error": "Only merchant may re-enable this card"
}

Cancel Gift Card

You can create a new card for the same customer and currency after cancelling the previous one.

Endpoint

DELETE https://api.chapa.link/card/9285944660
Authorization: Bearer {{API_KEY}}

No request body.

Success Response

{
  "status": "success",
  "message": "Gift card cancelled successfully",
  "data": null
}

Error Responses

Status	Message	When
`400`	Invalid card number	`card_number` path parameter is missing
`404`	Gift card not found	Card does not exist or does not belong to your business

{
  "status": "error",
  "message": "Gift card not found. The provided gift card does not exist",
  "error": "The provided gift card does not exist"
}

Tips

Always save card_number after creation
Use international format for phone numbers
Check available_amount before starting a payout

On this page

On this page