Send Money API Documentation

This document describes the internal API for sending money via Topremit.
It is confidential and for hiring/exercise purposes only.

Rest API Overview

For more information, please visit our REST API page to see usage limits, authentication, and other endpoints.

---

Endpoint

POST /v1/remittance/send

---

Description

Initiates a remittance transaction to a recipient. Use this endpoint to send money to supported countries with the specified service type. The remittance will only succeed if all required fields are provided and valid.

---

Headers

Header	Type	Description
Authorization	string	API key or bearer token for authentication
Content-Type	string	Must be application/json

Tips

Always include the Authorization header to avoid 401 Unauthorized errors.

---

Request Body Type Data

{
  "sender_id": "string",
  "recipient_id": "string",
  "amount": "number",
  "currency": "string",
  "service_type": "string",
  "payment_method": "string",
  "reference": "string"
}

---

Example Request Body

{
  "sender_id": "201925",
  "country": "PHL",
  "currency": "PHP",
  "service": "Bank Transfer (Normal)",
  "recipient_name": "Benecito Cabrera",
  "recipient_bank_account": "1234567890",
  "amount": 10000,
  "purpose": "Purchase Goods and Services"
}

---

Request Fields

Field	Type	Required	Description	Example
sender_id	string	✅	Unique ID of the sender	"201925"
country	string	✅	3-letter ISO country code	"PHL"
currency	string	✅	Currency code of the remittance	"PHP"
service	string	✅	The service type for the transfer	"Bank Transfer (Normal)"
recipient_name	string	✅	Name of the recipient	"Benecito Cabrera"
recipient_bank_account	string	✅	Recipient's bank account number	"1234567890"
amount	number	✅	Transfer amount in destination currency	10000
purpose	string	✅	Purpose of the transaction	"Purchase Goods and Services"

---

Response Body Type Data

{
  "ref_id": "string",
  "expiration_date": "string",
  "service": "string",
  "fx_rate": "string",
  "status": "string",
  "estimated_arrival": "string",
  "source": {
    "currency": "string",
    "amount": "string"
  },
  "destination": {
    "country": "string",
    "currency": "string",
    "amount": "string"
  },
  "fee": {
    "amount": "number",
    "currency": "string"
  }
}

---

Example Response Body

{
  "ref_id": "dfbae7e7-5271-4d63-bce0-a5c2367d9594",
  "expiration_date": "2025-06-25T15:00:00Z",
  "service": "Bank Transfer (Normal)",
  "fx_rate": "288.95",
  "status": "IN_PROGRESS",
  "estimated_arrival": "2025-06-27T15:00:00Z",
  "source": {
    "currency": "IDR",
    "amount": "2889500"
  },
  "destination": {
    "country": "PHL",
    "currency": "PHP",
    "amount": "10000.00"
  },
  "fee": {
    "amount": 45000,
    "currency": "IDR"
  }
}

---

Response Fields

Field	Type	Description	Example
ref_id	string (UUID)	Unique transaction reference	"dfbae7e7-5271-4d63-bce0-a5c2367d9594"
expiration_date	string (date-time)	Expiration of the transaction	"2025-06-25T15:00:00Z"
service	string	Service type used	"Bank Transfer (Normal)"
fx_rate	string	Exchange rate applied	"288.95"
status	string	Current status of transaction	"IN_PROGRESS"
estimated_arrival	string (date-time)	Estimated arrival of funds	"2025-06-27T15:00:00Z"
source.currency	string	Source currency	"IDR"
source.amount	string	Source amount	"2889500"
destination.country	string	Recipient country	"PHL"
destination.currency	string	Recipient currency	"PHP"
destination.amount	string	Amount to recipient	"10000.00"
fee.amount	number	Fee amount charged	45000
fee.currency	string	Fee currency	"IDR"

---

Possible Error Responses

HTTP Status	Description	Example
400	Bad Request - validation error	{ "error": "Missing required field: recipient_name" }
401	Unauthorized - missing or invalid API key	{ "error": "Unauthorized" }
429	Too many requests - rate limited	{ "error": "Too many requests, please retry later." }
500	Internal Server Error	{ "error": "Internal Server Error" }

Information

• 400 errors usually occur if any required field is missing or the value is invalid. Always check your payload before sending.

• 401 errors indicate invalid or missing Authorization header. Ensure your API key or bearer token is correct.

• 429 errors happen when the rate limit is exceeded. Implement retry logic with exponential backoff.

• 500 errors indicate an internal server issue. If you encounter this, please try again later or contact support.

warning

• All fields marked with ✅ in the Request Fields table are required. Missing or invalid values will result in a 400 Bad Request.

• Currency must match one of the supported codes (e.g., PHP, USD). The system will reject unsupported currencies.

• Ensure the recipient_bank_account is valid and belongs to the recipient; otherwise, the transfer may fail or be reversed.

• Do not expose your API key in client-side code. Always store it securely on the server.

Additional Tips / Tips Tambahan

• Always double-check amounts and recipient details before sending.

• Include a meaningful purpose for compliance.

• Check service limits to avoid rejection.

---