Create Recipient

POST /api-access/api/recipients

Create a new recipient for payments and transfers.

Authentication

Required Headers:

Authorization: HMAC-SHA256 PUBLIC_KEY:PRIVATE_KEY
X-Origin: third-party-api
X-Timestamp: 2025-10-12T14:30:00.000Z
Content-Type: application/json

Request

Base Required Fields (All Transaction Types):

The following fields are required for all recipients regardless of transaction type:

Parameter	Type	Description
first_name	string	Recipient's first name (minimum 1 character)
last_name	string	Recipient's last name (minimum 1 character)
transaction_type	string	Type of transaction. See Transaction Types
country	string	Country code (e.g., ca, bj, ci)
recipient_type	string	Recipient type. Values: transaction, reversal, all, withdrawal
language	string	Language preference. Values: en, fr

Additional Fields (Transaction-Specific):

These fields are required depending on the transaction_type:

Parameter	Type	Required	Description
phone	string	Conditional	Phone number (required for mobile_money)
email	string	Conditional	Email address (required for all except mobile_money and xpress_cash)
withdrawal_channel	string	Conditional	Cash withdrawal channel (required for xpress_cash). Values: ATM
account_number	string	Conditional	Bank account number. See Account Number Requirements
account_branch	string	Optional	Bank account branch
account_type	string	Optional	Account type. Values: corporate, savings, current
bank_code	string	Conditional	Bank code (required for bank_transfer_ach)
institution_number	string	Conditional	Institution number (required for eft)
transit_number	string	Conditional	Transit number (required for eft)
provider	string	Conditional	Mobile money provider (required for mobile_money)
payee_name	string	Conditional	Payee name (required for bill_pay)
payee_code	string	Conditional	6-digit payee code (required for bill_pay)
description	string	Optional	Description of the recipient
security_question	string	Optional	Security question
security_question_answer	string	Optional	Security question answer

Transaction Types

Available transaction_type values:

• interac_send - Interac e-Transfer
• eft - Electronic Funds Transfer
• bank_transfer_ach - ACH Bank Transfer
• bill_pay - Bill Payment (Canada only)
• mobile_money - Mobile Money Transfer
• xpress_cash - Cash Pickup
• ecobank_direct_credit - Ecobank Direct Credit

Account Number Requirements

The account_number field is required for:

• ecobank_direct_credit (Domestic transfers)
• eft (Electronic Funds Transfer)
• bank_transfer_ach (ACH Interbank Transfers)
• bill_pay (Bill Pay Transactions)

Validation Rules:

• Bill Pay: Minimum 8 characters
• Other types: Minimum 12 digits

Field Dependencies by Transaction Type

Mobile Money (mobile_money)

Required fields:

• phone
• country
• provider

Cash Pickup (xpress_cash)

Required fields:

• withdrawal_channel

EFT Transfer (eft)

Required fields:

• account_number
• transit_number
• institution_number
• email

ACH Transfer (bank_transfer_ach)

Required fields:

• account_number
• bank_code
• email

Bill Pay (bill_pay)

Required fields:

• account_number (min 8 characters)
• payee_name
• payee_code (6 digits)
• country (must be ca)
• email

Ecobank Direct Credit (ecobank_direct_credit)

Required fields:

• account_number
• email

Response

Success Response (200):

{
  "data": {
    "id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "phone": "string",
    "country": "string",
    "withdrawal_channel": "ATM",
    "account_number": "string",
    "account_branch": "string",
    "account_type": "corporate",
    "bank_code": "string",
    "institution_number": "string",
    "transit_number": "string",
    "security_question": "string",
    "security_question_answer": "string",
    "transaction_type": "interac_send",
    "recipient_type": "reversal",
    "language": "en",
    "created_at": "2025-10-12T18:05:57.998Z",
    "updated_at": "2025-10-12T18:05:57.998Z",
    "avatar": "string",
    "provider": "string",
    "payee_name": "string",
    "payee_code": "string",
    "user_id": "string",
    "business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "success": true,
  "message": "string",
  "detail": {}
}

Examples

Full Payload Example

cURL

curl -X POST "https://sandbox.mara.boo/api-access/api/recipients" \
  -H "Authorization: HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY" \
  -H "X-Origin: third-party-api" \
  -H "X-Timestamp: 2025-10-12T14:30:00.000Z" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+22997123456",
    "transaction_type": "mobile_money",
    "country": "bj",
    "email": "user@example.com",
    "withdrawal_channel": "ATM",
    "account_number": "123456789012",
    "account_branch": "Main Branch",
    "account_type": "corporate",
    "bank_code": "001",
    "institution_number": "123",
    "transit_number": "12345",
    "provider": "mtn",
    "payee_name": "Service Provider",
    "payee_code": "123456",
    "recipient_type": "transaction",
    "language": "en",
    "description": "Monthly payment recipient",
    "security_question": "What is your favorite color?",
    "security_question_answer": "Blue"
  }'

JavaScript

const response = await fetch('https://sandbox.mara.boo/api-access/api/recipients', {
  method: 'POST',
  headers: {
    'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
    'X-Origin': 'third-party-api',
    'X-Timestamp': '2025-10-12T14:30:00.000Z',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    first_name: "John",
    last_name: "Doe",
    phone: "+22997123456",
    transaction_type: "mobile_money",
    country: "bj",
    email: "user@example.com",
    withdrawal_channel: "ATM",
    account_number: "123456789012",
    account_branch: "Main Branch",
    account_type: "corporate",
    bank_code: "001",
    institution_number: "123",
    transit_number: "12345",
    provider: "mtn",
    payee_name: "Service Provider",
    payee_code: "123456",
    recipient_type: "transaction",
    language: "en",
    description: "Monthly payment recipient",
    security_question: "What is your favorite color?",
    security_question_answer: "Blue"
  })
});

const data = await response.json();

Python

import requests

response = requests.post(
    'https://sandbox.mara.boo/api-access/api/recipients',
    headers={
        'Authorization': 'HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY',
        'X-Origin': 'third-party-api',
        'X-Timestamp': '2025-10-12T14:30:00.000Z',
        'Content-Type': 'application/json'
    },
    json={
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+22997123456",
        "transaction_type": "mobile_money",
        "country": "bj",
        "email": "user@example.com",
        "withdrawal_channel": "ATM",
        "account_number": "123456789012",
        "account_branch": "Main Branch",
        "account_type": "corporate",
        "bank_code": "001",
        "institution_number": "123",
        "transit_number": "12345",
        "provider": "mtn",
        "payee_name": "Service Provider",
        "payee_code": "123456",
        "recipient_type": "transaction",
        "language": "en",
        "description": "Monthly payment recipient",
        "security_question": "What is your favorite color?",
        "security_question_answer": "Blue"
    }
)

data = response.json()

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "io/ioutil"
)

func main() {
    payload := map[string]interface{}{
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+22997123456",
        "transaction_type": "mobile_money",
        "country": "bj",
        "email": "user@example.com",
        "withdrawal_channel": "ATM",
        "account_number": "123456789012",
        "account_branch": "Main Branch",
        "account_type": "corporate",
        "bank_code": "001",
        "institution_number": "123",
        "transit_number": "12345",
        "provider": "mtn",
        "payee_name": "Service Provider",
        "payee_code": "123456",
        "recipient_type": "transaction",
        "language": "en",
        "description": "Monthly payment recipient",
        "security_question": "What is your favorite color?",
        "security_question_answer": "Blue",
    }

    jsonData, _ := json.Marshal(payload)

    client := &http.Client{}
    req, _ := http.NewRequest("POST", "https://sandbox.mara.boo/api-access/api/recipients", bytes.NewBuffer(jsonData))

    req.Header.Set("Authorization", "HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY")
    req.Header.Set("X-Origin", "third-party-api")
    req.Header.Set("X-Timestamp", "2025-10-12T14:30:00.000Z")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
}

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

String jsonPayload = """
{
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+22997123456",
  "transaction_type": "mobile_money",
  "country": "bj",
  "email": "user@example.com",
  "withdrawal_channel": "ATM",
  "account_number": "123456789012",
  "account_branch": "Main Branch",
  "account_type": "corporate",
  "bank_code": "001",
  "institution_number": "123",
  "transit_number": "12345",
  "provider": "mtn",
  "payee_name": "Service Provider",
  "payee_code": "123456",
  "recipient_type": "transaction",
  "language": "en",
  "description": "Monthly payment recipient",
  "security_question": "What is your favorite color?",
  "security_question_answer": "Blue"
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.mara.boo/api-access/api/recipients"))
    .header("Authorization", "HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY")
    .header("X-Origin", "third-party-api")
    .header("X-Timestamp", "2025-10-12T14:30:00.000Z")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

var payload = new
{
    first_name = "John",
    last_name = "Doe",
    phone = "+22997123456",
    transaction_type = "mobile_money",
    country = "bj",
    email = "user@example.com",
    withdrawal_channel = "ATM",
    account_number = "123456789012",
    account_branch = "Main Branch",
    account_type = "corporate",
    bank_code = "001",
    institution_number = "123",
    transit_number = "12345",
    provider = "mtn",
    payee_name = "Service Provider",
    payee_code = "123456",
    recipient_type = "transaction",
    language = "en",
    description = "Monthly payment recipient",
    security_question = "What is your favorite color?",
    security_question_answer = "Blue"
};

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://sandbox.mara.boo/api-access/api/recipients");

request.Headers.Add("Authorization", "HMAC-SHA256 YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY");
request.Headers.Add("X-Origin", "third-party-api");
request.Headers.Add("X-Timestamp", "2025-10-12T14:30:00.000Z");

var jsonContent = JsonSerializer.Serialize(payload);
request.Content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var content = await response.Content.ReadAsStringAsync();

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid authentication
403	Forbidden - Missing required headers
422	Validation Error - Field validation failed
500	Internal Server Error

Common Validation Errors

{
  "success": false,
  "message": "Validation error",
  "mb_error_code": "validation_error",
  "errors": {
    "withdrawal_channel": ["withdrawal_channel is required for Transaction XpressCash"],
    "account_number": ["account_number is required for Electronic funds transfer (EFT)"],
    "email": ["email is required"],
    "phone": ["phone is required for mobile_money transfer"],
    "provider": ["provider is required for mobile_money transfer"],
    "payee_code": ["payee_code must be 6 digits"]
  }
}

Related

• Get Recipients
• Get Recipient