BALAD CORP APIs/Link/Transactions API
The APIs/Link/Transactions API from BALAD CORP — 7 operation(s) for apis/link/transactions.
OpenAPI Specification
openapi: 3.0.1
info:
title: Balad Gateway APIs/Authentication APIs/Link/Transactions API
description: Balad Gateway APIs — a suite of RESTful endpoints for secure inward cross-border remittances and payouts into Egypt (bank transfers, mobile wallets, cash pickup). Covers authentication, exchange rates, balance, secrets management, lookups, and the full transaction lifecycle. Assembled by API Evangelist from the provider's per-operation OpenAPI fragments published on developers.balad.tech.
version: 1.0.0
contact:
name: Balad Support
email: support@balad.me
url: https://developers.balad.tech/
servers: []
tags:
- name: APIs/Link/Transactions
paths:
/remit-api/v1/transactions/calculate-receiving-amount:
post:
summary: Calculate receiving amount
deprecated: false
description: 'This API endpoint calculates and retrieves the receiving amount based on the sending amount. The transaction type is optional; if provided, the API will return the receiving amount in the currency associated with the specified transaction type. If the transaction type is not provided, the API will return the receiving amount for all available currencies.
**Request Params**
| **Parameter** | **Type** | **Mandatory** | **Remarks** |
| --- | --- | --- | --- |
| amount_usd | Integer | Y | This is the amount being sent and needs to be used for calculating the corresponding receiving amount. |
| transaction_type | Integer | N | The transaction type <br>1- Cash <br>2 - Account Credit <br>3 - Wallet <br>4 -Credit/Debit Card |
**Response Params**
| **SI No** | **Parameter** | **Remarks** |
| --- | --- | --- |
| 1 | currency_code | the receiving currency |
| 2 | amount | the receiving amount |'
tags:
- APIs/Link/Transactions
parameters:
- name: Content-Type
in: header
description: ''
required: false
example: application/json
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties: {}
x-apidog-orders: []
example: "{\r\n \"amount_usd\":XXXX,\r\n \"transaction_type\":X\r\n}"
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties: {}
x-apidog-orders: []
example: "{\r\n \"data\": [\r\n {\r\n \"currency_code\": \"EGP\",\r\n \"amount\":XXX\r\n },\r\n {\r\n \"currency_code\": \"USD\",\r\n \"amount\":XXX\r\n }\r\n ],\r\n \"errors\": null\r\n}\r\n"
headers: {}
x-apidog-name: EG Country
security:
- Balad Token: []
x-apidog:
required: true
schemeGroups:
- id: 87aTaQp8pR3_G2Uh_UKds
schemeIds:
- Balad Token
use:
id: 87aTaQp8pR3_G2Uh_UKds
x-apidog-folder: APIs/Link/Transactions
x-apidog-status: released
x-run-in-apidog: https://app.apidog.com/web/project/1056134/apis/api-20919923-run
/remit-api/v1/transactions/cancel:
post:
summary: Cancel transaction
deprecated: false
description: 'This method handles transaction cancellation within the Balad Remit system.
### Cancellable Transactions
Only the following transaction statuses can be cancelled. Each status results in either an **Instant Cancel (Code 7)** or **Under Cancellation (Code 22)** depending on the case.
| Transaction Status Code | Transaction Status | Transaction Type | Resulting Status |
|-------------|-------------------------------|------------------|------------------------------|
| **0** | Created | All | **7 (Cancelled)** |
| **2** | In Progress | Cash | **22 (Under Cancellation)** |
| **8** | Pending | All | **7 (Cancelled)** |
| **11** | Balad Compliance Suspended | All | **7 (Cancelled)** |
| **12** | Balad Compliance Approved | All | **7 (Cancelled)** |
| **16** | Bank Compliance Suspended | Cash | **22 (Under Cancellation)** |
| **19** | Ready For Pickup | Cash | **22 (Under Cancellation)** |
---
### Cancellation Reasons
Use one of the following values in the **reason** field when submitting a cancellation request.
If none of the predefined reasons apply, set `reason` to **13** and include your explanation in `other_reason`.
| Code | Reason |
| ------ | ----------------------------------------------------- |
| **1** | I entered the wrong recipient name |
| **2** | I entered the wrong account, wallet, or phone number |
| **3** | I chose the wrong bank, wallet, or payout method |
| **4** | I entered the wrong amount |
| **5** | I no longer need to send this transfer |
| **6** | The recipient no longer needs the money |
| **7** | This is a duplicate transfer |
| **8** | The transfer is taking too long |
| **9** | I will send the money using a different method |
| **11** | Fees or exchange rate are not acceptable |
| **12** | I created this transaction by mistake (test or trial) |
| **13** | Other reason (please specify) |
---
'
tags:
- APIs/Link/Transactions
parameters:
- name: Content-Type
in: header
description: ''
required: false
example: application/json
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
remitter_reference_no:
type: string
reason:
type: integer
other_reason:
type: string
required:
- remitter_reference_no
- reason
x-apidog-orders:
- remitter_reference_no
- reason
- other_reason
example:
remitter_reference_no: BALADLINK-XXXXXXXXXX
reason: 1
other_reason: ''
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
remitter_reference_no:
type: string
transaction_status_code:
type: integer
transaction_status_description:
type: string
required:
- remitter_reference_no
- transaction_status_code
- transaction_status_description
x-apidog-orders:
- remitter_reference_no
- transaction_status_code
- transaction_status_description
errors:
type: 'null'
required:
- data
- errors
x-apidog-orders:
- data
- errors
examples:
'1':
summary: Under Cancellation
value:
data:
remitter_reference_no: BALADLINK-XXXXXXXXXX
transaction_status_code: 22
transaction_status_description: Under Cancellation
errors: null
'2':
summary: Instant Cancel
value:
data:
remitter_reference_no: BALADLINK-XXXXXXXXXX
transaction_status_code: 7
transaction_status_description: Canceled
errors: null
headers: {}
x-apidog-name: Success
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: 'null'
errors:
type: array
items:
type: object
properties:
code:
type: integer
message:
type: string
field:
type: 'null'
x-apidog-orders:
- code
- message
- field
required:
- data
- errors
x-apidog-orders:
- data
- errors
example:
data: null
errors:
- code: 113
message: Cancellation Not Available
field: null
additionalInfo: null
headers: {}
x-apidog-name: Cancellation Not Available
x-400:Reference No Not found:
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: 'null'
errors:
type: array
items:
type: object
properties:
code:
type: integer
message:
type: string
field:
type: 'null'
additionalInfo:
type: 'null'
x-apidog-orders:
- code
- message
- field
- additionalInfo
required:
- data
- errors
x-apidog-orders:
- data
- errors
example:
data: null
errors:
- code: 106
message: Invalid Reference Number
field: null
additionalInfo: null
headers: {}
x-apidog-name: Reference No Not found
x-400:Transaction already canceled:
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: 'null'
errors:
type: array
items:
type: object
properties:
code:
type: integer
message:
type: string
field:
type: 'null'
additionalInfo:
type: 'null'
x-apidog-orders:
- code
- message
- field
- additionalInfo
required:
- data
- errors
x-apidog-orders:
- data
- errors
example:
data: null
errors:
- code: 169
message: Transaction already canceled before
field: null
additionalInfo: null
headers: {}
x-apidog-name: Transaction already canceled
security:
- Balad Token: []
x-apidog:
required: true
schemeGroups:
- id: 87aTaQp8pR3_G2Uh_UKds
schemeIds:
- Balad Token
use:
id: 87aTaQp8pR3_G2Uh_UKds
x-apidog-folder: APIs/Link/Transactions
x-apidog-status: released
x-run-in-apidog: https://app.apidog.com/web/project/1056134/apis/api-20919919-run
/remit-api/v1/transactions:
post:
summary: Create transaction
deprecated: false
description: "This endpoint is used to **initiate a money transfer transaction** through Balad’s Collection API. \nIt supports multiple transaction types (Cash, Card, Bank Account and Wallet) and requires sender, receiver, and transaction details to be passed in the request body. \n\n ---\n\n<AccordionGroup>\n <Accordion title=\"Sender Details\" defaultOpen>\n\n| **Parameter** | **Remarks** |\n| --- | --- |\n| sender_first_name | First or full legal name. Must match valid ID. Could be sender first name only or sender full name (Full Name must be the full legal name of the sender and must exactly match the name as it appears on the sender's valid ID.) |\n| sender_middle_name | Middle name. Same character rules as first name. |\n| sender_last_name | Last name. Same character rules as first name. |\n| sender_address | Full sender address. |\n| sender_dateofbirth | Format: `DD-MMM-YYYY`. Example: `01-JUN-2020`. |\n| sender_contact_no | Contact number. |\n| sender_identity | Identity type: 1 = Passport, 2 = Government-issued ID. |\n| sender_identity_no | ID/Passport number. Allowed: periods (.), commas (,), underscores (_), hyphens (-), space ( ). |\n| sender_identity_expiry_date | ID Expiry Date. Format: `DD-MMM-YYYY`. Must not be expired. |\n| sender_nationality | ISO alpha-2 country code (e.g., `US`, `EG`). |\n| sender_country_code | ISO alpha-2 country code of residence. |\n| sender_country_of_birth | Country of birth, valid country string (e.g., `Egypt`, `United States of America`). |\n| sender_gender | 1 = Male, 2 = Female. |\n\n </Accordion>\n\n <Accordion title=\"Receiver Details\">\n\n | **Parameter** | **Remarks** |\n | --- | --- |\n | receiver_first_name | First or full legal name in English. Must match valid ID. |\n | receiver_middle_name | Middle name. Same character rules as first name. |\n | receiver_last_name | Last name. Same character rules as first name.|\n | receiver_address | Required in some cases (e.g., Account transfer in USD except bank code `BDC`). |\n | receiver_contact_no | Valid phone number. Egyptian format supported. In case of cash, if provided the receiver will receive SMS with transaction details on this number Examples: `+20101111145`, `020101111145`, `01011111145`. |\n | receiver_identity_type | Identity type: 1 = Passport, 2 = Government-issued ID (default 2 if not sent). |\n | receiver_identity_no | ID/Passport number. Allowed: periods (.), commas (,), underscores (_), hyphens (-), space ( ). |\n | receiver_gender | 1 = Male, 2 = Female. |\n\n </Accordion>\n\n <Accordion title=\"Transaction Details\">\n\n | **Parameter** | **Remarks** |\n | --- | --- |\n | transaction_type | 1 = Cash, 2 = Account Credit, 3 = Wallet, 4 = Card. |\n | remitter_reference_no | Unique agent reference. Allowed: A–Z, a–z, 0–9, dash (-). |\n | sending_currency_code | ISO 4217 currency code. Examples: `EGP`, `USD`. |\n | amount | Amount with up to 2 decimals. Example: `2500.50`. |\n | account_no | Account/Wallet/Card number. Rules: <br>• 16 digits for card <br>• 11 digits for wallet (Egyptian phone number format) <br>Examples: `+201055555333`, `01055555333`. <br>• IBAN for USD bank transfers <br>• Required in case transaction type 'Cash' and bank code 'POST' |\n | receiver_bank_code | Bank code (e.g., `BDC`, `POST`). Required in some cases. [Banks List](https://developers.balad.tech/banks-list-20919916e0.md) |\n | source_of_remittance | Source code of transaction. List available via sources endpoint. [Sources List](https://developers.balad.tech/sources-list-20919915e0.md) |\n | purpose | Purpose code of transaction. List available via purposes endpoint. [Purposes List](https://developers.balad.tech/purposes-list-20919914e0.md)|\n | value_date | Format: `DD-MMM-YYYY`. Example: `01-JUN-2020`. Must be today or later. |\n | business_model_type | Business model: 1 = C2C (default)|\n\n </Accordion>\n</AccordionGroup>\n\n\n## Required Fields \n\n| Field | Cash Pickup (`1`) | Bank Account (`2`) | Wallet (`3`) |\n|---------------------------|-------------------|--------------------|--------------|\n| **transaction_type** | ✅ | ✅ | ✅ |\n| **remitter_reference_no** | ✅ | ✅ | ✅ |\n| **sender_first_name** | ✅ | ✅ | ✅ |\n| **sender_last_name** | ✅ | ✅ | ❌ |\n| **sender_address** | ✅ | ✅ | ✅ |\n| **sender_dateofbirth** | ✅ | ✅ | ✅ |\n| **sender_contact_no** | ❌ | ❌ | ❌ |\n| **sender_identity (type)**| ❌ | ❌ | ❌ |\n| **sender_identity_no** | ❌ | ❌ | ❌ |\n| **sender_identity_expiry_date** | ❌ | ❌ | ❌ |\n| **sender_nationality** | ✅ | ✅ | ✅ |\n| **sender_country_code** | ✅ | ✅ | ✅ |\n| **receiver_first_name** | ✅ | ✅ | ✅ |\n| **receiver_last_name** | ❌ | ❌ | ❌ |\n| **receiver_address** | ❌ | ✅ | ❌ |\n| **receiver_contact_no** | ✅ | ❌ | ✅ |\n| **receiver_identity_type** | ❌ | ❌ | ❌ |\n| **receiver_identity_no** | ❌ | ❌ | ❌ |\n| **receiver_gender** | ❌ | ❌ | ❌ |\n| **receiver_relationship** | ❌ | ❌ | ❌ |\n| **account_no** | ❌ | ✅ | ✅ |\n| **receiver_bank_code** | ✅ | ✅ | ❌ |\n| **sending_currency_code** | ✅ | ✅ | ✅ |\n| **amount** | ✅ | ✅ | ✅ |\n| **source_of_remittance** | ❌ | ❌ | ❌ |\n| **purpose** | ✅ | ✅ | ✅ |\n| **value_date** | ❌ | ❌ | ❌ |\n| **business_model_type** | ❌ | ❌ | ❌ |\n\n--- \n\n"
tags:
- APIs/Link/Transactions
parameters:
- name: X-Country-Code
in: header
description: ''
required: false
example: ''
schema:
type: string
- name: X-IV-Key
in: header
description: ''
required: false
example: ''
schema:
type: string
- name: Content-Type
in: header
description: ''
required: false
example: application/json
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
transaction_type:
type: integer
description: 'Transaction type: 1=Cash, 2=Account Credit, 3=Wallet, 4=Card'
enum:
- 1
- 2
- 3
- 4
examples:
- 1
x-apidog-enum:
- value: 1
name: Cash
description: Cash payout at agent location
- value: 2
name: Account
description: Direct credit to bank account
- value: 3
name: Wallet
description: Credit to mobile wallet
- value: 4
name: Card
description: Credit to debit/credit card
remitter_reference_no:
type: string
maxLength: 50
pattern: ^[A-Za-z0-9-]+$
description: Unique transaction reference number assigned by the sending agent
examples:
- TXN-20230901
sender_first_name:
type: string
maxLength: 50
description: Sender first name or full name
examples:
- Mohamed
sender_middle_name:
type: string
maxLength: 50
description: Sender middle name (optional)
examples:
- Ahmed
sender_last_name:
type: string
maxLength: 50
description: Sender last name (required if first name is not full name)
examples:
- Hassan
sender_address:
type: string
description: Full residential address of sender
maxLength: 200
examples:
- 123 Nile Street, Cairo
sender_dateofbirth:
type: string
pattern: ^\d{2}-[A-Z]{3}-\d{4}$
description: Sender date of birth in DD-MMM-YYYY format
examples:
- 01-JUN-1990
sender_contact_no:
type: string
maxLength: 20
description: Sender contact number
examples:
- '+201011111145'
sender_identity:
type: integer
enum:
- 1
- 2
description: 'Sender ID type: 1=Passport, 2=Government ID'
examples:
- 2
x-apidog-enum:
- value: 1
name: Passport
- value: 2
name: Government ID
sender_identity_no:
type: string
description: Sender ID number
maxLength: 50
examples:
- '29804151502123'
sender_identity_expiry_date:
type: string
pattern: ^\d{2}-[A-Z]{3}-\d{4}$
description: Expiry date of ID (optional, DD-MMM-YYYY format)
examples:
- 01-JUN-2030
sender_nationality:
type: string
maxLength: 2
description: Sender nationality (ISO 3166-1 alpha-2)
examples:
- EG
sender_country_code:
type: string
maxLength: 2
description: Country code of sender's residence (ISO 3166-1 alpha-2)
examples:
- EG
sender_country_of_birth:
type: string
maxLength: 100
description: Sender country of birth (optional)
examples:
- Egypt
sender_gender:
type: integer
enum:
- 1
- 2
description: 'Sender gender: 1=Male, 2=Female'
examples:
- 1
x-apidog-enum:
- value: 1
name: Male
- value: 2
name: Female
receiver_first_name:
type: string
maxLength: 50
description: Receiver first name or full name (English only)
examples:
- John
receiver_middle_name:
type: string
maxLength: 50
description: Receiver middle name (optional)
examples:
- Michael
receiver_last_name:
type: string
maxLength: 50
description: Receiver last name (optional if full name in first_name)
examples:
- Smith
receiver_address:
type: string
description: Receiver residential address (mandatory for Account/Card, optional for Cash/Wallet)
maxLength: 200
examples:
- 45 Park Avenue, NY
receiver_contact_no:
type: string
maxLength: 20
description: Receiver contact number (mandatory for Wallet/Card, optional for Cash/Account)
examples:
- '+201011111145'
receiver_identity_type:
type: integer
enum:
- 1
- 2
description: Receiver ID type (mandatory for Cash payout). 1=Passport, 2=Government ID
examples:
- 2
receiver_identity_no:
type: string
maxLength: 50
description: 'Receiver ID number (mandatory for Cash payout). Government ID: It''s Egyptian National Identity'
examples:
- '29804151502123'
receiver_gender:
type: integer
enum:
- 1
- 2
description: Receiver gender (optional)
examples:
- 1
receiver_relationship:
type: string
maxLength: 50
description: Relationship of receiver to sender (optional, e.g., BROTHER, MOTHER)
examples:
- BROTHER
sending_currency_code:
type: string
maxLength: 3
description: Sending currency ISO 4217 code. The currency beneficiary/receiver will receive money in
examples:
- USD
amount:
type: string
description: Transaction amount with up to two decimal places
pattern: ^\d+(\.\d{1,2})?$
examples:
- '2500.50'
account_no:
type: string
minLength: 4
maxLength: 29
description: Account/Wallet/Card number (mandatory for Account, Wallet, and Card transfers)
examples:
- '01055555333'
receiver_bank_code:
type: string
maxLength: 4
description: Receiver bank code (mandatory for Account transfer if bank is required)
examples:
- BDC
source_of_remittance:
type: string
maxLength: 3
description: Source code of transaction funds (optional, ISO/custom code)
examples:
- SAL
purpose:
type: string
maxLength: 3
description: Purpose code of transaction (ISO/custom code)
examples:
- FAM
value_date:
type: string
pattern: ^\d{2}-[A-Z]{3}-\d{4}$
description: Value date (>= today, optional)
examples:
- 05-SEP-2025
business_model_type:
type: integer
enum:
- 1
- 2
description: 'Business model type: 1=C2C (Person-to-Person)'
examples:
- 1
x-apidog-enum:
- value: 1
name: C2C
description: Person-to-Person remittance
required:
- transaction_type
- remitter_reference_no
- sender_first_name
- sender_last_name
- sender_address
- sender_dateofbirth
- sender_identity
- sender_identity_no
- sender_nationality
- sender_country_code
- receiver_first_name
- sending_currency_code
- amount
- purpose
x-apidog-orders:
- transaction_type
- remitter_reference_no
- sender_first_name
- sender_middle_name
- sender_last_name
- sender_address
- sender_dateofbirth
- sender_contact_no
- sender_identity
- sender_identity_no
- sender_identity_expiry_date
- sender_nationality
- sender_country_code
- sender_country_of_birth
- sender_gender
- receiver_first_name
- receiver_middle_name
- receiver_last_name
- receiver_address
- receiver_contact_no
- receiver_identity_type
- receiver_identity_no
- receiver_gender
- receiver_relationship
- sending_currency_code
- amount
- account_no
- receiver_bank_code
- source_of_remittance
- purpose
- value_date
- business_model_type
examples:
'1':
value:
transaction_type: 1
remitter_reference_no: '{{refNo}}'
sender_first_name: SHOHAIB KHAN
sender_last_name: MOHAMMAD
sender_address: KUWAIT ROAD KUWAIT
sender_dateofbirth: 10-May-1980
sender_identity: 2
sender_identity_no: PK12255100
sender_identity_expiry_date: 23-Jul-2027
sender_nationality: EG
sender_country_code: KW
sender_contact_no: '96539053100'
receiver_first_name: Mohammad Faisal Rashid
receiver_last_name: Mustafa
receiver_address: EGYPT
receiver_identity_type: 2
receiver_nationality: EG
receiver_contact_no: '01222222103'
sending_currency_code: EGP
amount: '5800'
account_no: '01234323456'
receiver_bank_code: BDC
source_of_remittance: '001'
purpose: '002'
summary: Cash Transaction
'2':
value:
transaction_type: 2
remitter_reference_no: '{{refNo}}'
sender_first_name: SHOHAIB KHAN
sender_last_name: MOHAMMAD
sender_address: KUWAIT ROAD KUWAIT
sender_dateofbirth: 10-May-1980
sender_identity: 2
sender_identity_no: PK12255100
sender
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/balad-corp/refs/heads/main/openapi/balad-corp-apis-link-transactions-api-openapi.yml