POST /inbound

POST /api/v1/remittance/inbound

Submit a money transfer to a beneficiary's DRC mobile money wallet or FBN Bank cash pickup. Returns HTTP 202 Accepted with an acknowledgement. The final status (Successful / Failed) is delivered later via webhook.

Auth: Basic merchant_code:merchant_secret

Required fields

All fields below are hard-required. A missing value returns RMT-1005 MISSING_FIELD (or RMT-1018 for the address either-or).

Transaction identity & routing

Field	Type	Description
amount	number	Transaction amount in source currency.
currency	string	Source currency. See supported currencies. Receiver always gets USD on DRC corridor.
customer_number	string	Beneficiary MSISDN (243…).
reference	string	Your unique transfer reference (max 80 chars). Idempotent — a repeat call returns the first result.
operator	string	mpesa, airtel, orange, afrimoney, or fbnbank (cash pickup).
expected_receiver_name	string	Receiver name confirmed with your end-user. Fuzzy-matched against the telco record.

Sender KYC — FATF R.16 + BCC RTS Art.66

Field	Type	Description
sender_first_name	string	Legal first name as on the sender's identity document.
sender_last_name	string	Legal last name as on the sender's identity document.
sender_nationality	string	Sender nationality.
sender_birthdate	string (ISO date)	Date of birth, YYYY-MM-DD.
sender_birthplace	string	City of birth.
sender_document_type	string (enum)	One of: PASSPORT, NATIONAL_ID, DRIVING_LICENCE, VOTER_CARD, OTHER. Invalid values return RMT-1015.
identity_number	string	Sender ID / passport number matching sender_document_type.
sending_country	string	ISO-3166-1 alpha-2 country code of the sending country.

Receiver KYC — FATF R.16 + BCC RTS Art.66

Field	Type	Description
receiver_first_name	string	Legal first name.
receiver_last_name	string	Legal last name.
receiver_nationality	string	Receiver nationality.
receiver_birthdate	string (ISO date)	YYYY-MM-DD.
receiver_document_type	string (enum)	One of: PASSPORT, NATIONAL_ID, DRIVING_LICENCE, VOTER_CARD. Required for all operators, not just cash pickup.
receiver_document_number	string	Receiver ID / passport number.
receiving_country	string	ISO country code (typically CD for DRC).
receiver_birthplace	string	Receiver city of birth.
receiver_current_address or receiver_permanent_address	string	At least one must be provided. Missing both returns RMT-1018.

Transaction context — FATF R.16

Field	Type	Description
reason_of_transaction	string (enum)	FAMILY_SUPPORT, EDUCATION, MEDICAL, BUSINESS_PAYMENT, SALARY, GIFT, SAVINGS, PROPERTY_PURCHASE, TRAVEL, LOAN_REPAYMENT, INVESTMENT, CONSTRUCTION, RENT, GENERAL, FUEL, REPAIRS, PERSONAL_CARE, FOOD_AND_GROCERIES, TRANSPORT, SHOPPING, ENTERTAINMENT, DONATIONS, OTHER (23 values). Invalid → RMT-1016.
source_of_funds	string (enum)	SALARY, BUSINESS_INCOME, SAVINGS, INVESTMENT, PENSION, GIFT, LOAN, SALE_OF_ASSET, INHERITANCE, OTHER. Invalid → RMT-1017.

Sender identity extras — Vodacom M-Pesa IMT transfer mandatory

Promoted to hard-required 2026-10-13 (v2.4). Vodacom's M-Pesa IMT transfer step rejects the live payout with INS-10005 when any of these are missing, even though the switch accepts validation. Enforcing them here lets you catch the gap at submission with RMT-1005 instead of a late silent Submitted → Failed transition.

Field	Type	Description
sender_city	string	Sender city of residence.
current_address	string	Sender full street address (line 1).
profession	string	Sender occupation / profession.
document_issue_date	string (ISO date)	Sender ID / passport issue date, YYYY-MM-DD.
document_expiration_date	string (ISO date)	Sender ID / passport expiry date, YYYY-MM-DD.
permanent_address	string	Sender permanent address. May be the same string as current_address if the sender has a single address.
sender_msisdn	string	The originating sender's own MSISDN (not the beneficiary's). Send "" for cash-counter (Western Union guichet) and web-only channels that have no sender MSISDN. Used by Vodacom Reporting.
sender_middle_name	string	Legal middle name as on the sender's identity document. Send "" when the sender has no middle name.
receiver_middle_name	string	Legal middle name as on the receiver's identity document. Send "" when the receiver has no middle name.

Optional fields

Only three fields remain optional — all three are either internal metadata or a per-request override of a merchant-channel default.

Field	Type	Description
reason_details	string	Free-text qualifier of reason_of_transaction. Example: reason_of_transaction=EDUCATION, reason_details="tuition for Nairobi university".
provider_name	string	Sender-side provider label if useful for your reconciliation.
callback_url	string	Per-request webhook URL override. If unset, uses the merchant-channel default.

Full-compliance request example

curl -X POST https://staging.remittance.gofreshpay.com/api/v1/remittance/inbound \
  -u 'MKA-XXXX-XXXX:sk_live_XXXXX' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount":                    10,
    "currency":                  "USD",
    "customer_number":           "243812345678",
    "reference":                 "TXN_001",
    "operator":                  "mpesa",
    "expected_receiver_name":    "Marie Kabila",

    "sender_first_name":         "John",
    "sender_middle_name":        "",
    "sender_last_name":          "Doe",
    "sender_nationality":        "Ugandan",
    "sender_birthdate":          "1985-04-12",
    "sender_birthplace":         "Kampala",
    "sender_document_type":      "PASSPORT",
    "identity_number":           "UG123456789",
    "sending_country":           "UG",
    "sender_city":               "Kampala",
    "current_address":           "Plot 42, Nakasero Hill Road, Kampala",
    "permanent_address":         "Plot 42, Nakasero Hill Road, Kampala",
    "profession":                "Software Engineer",
    "document_issue_date":       "2020-04-12",
    "document_expiration_date":  "2030-04-11",
    "sender_msisdn":             "256770000001",

    "receiver_first_name":       "Marie",
    "receiver_middle_name":      "",
    "receiver_last_name":        "Kabila",
    "receiver_nationality":      "Congolaise",
    "receiver_birthdate":        "1990-08-22",
    "receiver_birthplace":       "Kinshasa",
    "receiver_document_type":    "NATIONAL_ID",
    "receiver_document_number":  "CD-NAT-990822-4567",
    "receiver_current_address":  "Avenue Kabambare 12, Gombe, Kinshasa",
    "receiving_country":         "CD",

    "reason_of_transaction":     "FAMILY_SUPPORT",
    "source_of_funds":           "SALARY",

    "reason_details":            "monthly family support"
  }'

Response (202 Accepted)

{
  "status": "accepted",
  "message": "Transaction received and is being processed. Final status will be sent via callback.",
  "data": {
    "transaction_id":  "IMT-IN-20260814-A1B2C3-D4E5",
    "reference":       "TXN_001",
    "amount":          10,
    "currency":        "USD",
    "operator":        "mpesa",
    "customer_number": "243812345678",
    "subscriber_name": "MARIE KABILA",
    "created_at":      "2026-08-14T14:00:00.000000"
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

Errors

RMT-1005 — missing required field

{
  "status": "error",
  "error": {
    "code": "RMT-1005",
    "field": "sender_birthplace",
    "message": "Required field missing: sender_birthplace"
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

For expected_receiver_name specifically, the response also includes a telco_name_hint so you can retry with the right name without re-calling /account-lookup:

{
  "status": "error",
  "error": {
    "code": "RMT-1005",
    "field": "expected_receiver_name",
    "message": "Required field missing: expected_receiver_name.",
    "telco_name_hint": "MARIE KABILA"
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

RMT-1015 / 1016 / 1017 — invalid enum value

{
  "status": "error",
  "error": {
    "code": "RMT-1016",
    "field": "reason_of_transaction",
    "message": "reason_of_transaction must be one of ['BUSINESS_PAYMENT', 'CONSTRUCTION', 'DONATIONS', 'EDUCATION', 'ENTERTAINMENT', 'FAMILY_SUPPORT', 'FOOD_AND_GROCERIES', 'FUEL', 'GENERAL', 'GIFT', 'INVESTMENT', 'LOAN_REPAYMENT', 'MEDICAL', 'OTHER', 'PERSONAL_CARE', 'PROPERTY_PURCHASE', 'RENT', 'REPAIRS', 'SALARY', 'SAVINGS', 'SHOPPING', 'TRANSPORT', 'TRAVEL']"
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

RMT-1018 — both receiver addresses missing

{
  "status": "error",
  "error": {
    "code": "RMT-1018",
    "field": "receiver_current_address|receiver_permanent_address",
    "message": "At least one of receiver_current_address or receiver_permanent_address is required"
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

RMT-4006 — receiver name mismatch

{
  "status": "error",
  "error": {
    "code":     "RMT-4006",
    "message":  "Receiver name mismatch with telco record",
    "expected": "John Smith",
    "telco":    "MARIE KABILA",
    "score":    0.0,
    "reason":   "insufficient match: 0/2 matched, unmatched=['john', 'smith']"
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

Test cases in Postman

The Postman collection includes 20 test cases for /inbound:

• TC-INB-001 to TC-INB-009 — happy paths + variants (M-Pesa, Airtel, Orange, FX conversion, duplicate reference…)
• TC-INB-NAME-001 / 002 / 004 — name-match tests (missing, mismatch, happy path)
• TC-INB-KYC-001 to TC-INB-KYC-008 — the new v2.1 KYC field tests (missing sender_birthplace, invalid enums, both addresses missing, full-compliance happy path)

See also

• Aggregator model — who owns which side of the KYC
• Compliance & KYC — the exhaustive rules Moko enforces
• Callbacks — how the final status reaches you
• /account-lookup — mandatory pre-flight to fetch the telco name