Initiate Payout with beneficiary

🚧
Restrictions
Upon initialising a new payout, a validation will be carried out on each account to ensure compliance with the set conditions configured for payouts. The conditions will be pre-determined with the financial partner.
Validation Rules

Account lookup for each beneficiaries

Amount Validation: Each payout must be less than or equals to configured value

Each beneficiary mustn’t have received a payout over configured value under 24 hrs.

Confirm Business payout holding currency can settle all payout to payout recipients.

A proper response is returned upon a failed validation. See sample below:

Error Response on Amount Validation

{
    "status": 400,
    "data": null,
    "message": "error has occurred",
    "error": {
        "id": "18239c29-746c-479d-9d4a-4a6dba993193",
        "details": "rpc error: code = Unknown desc = maximum amount per payout of NGN is 1000000.000000",
        "message": "Maximum amount per payout of NGN is 1000000.000000."
    }
}

{
    "code": 400,
    "data": null,
    "message": "error has occurred",
    "error": {
        "id": "61744938-4624-4285-a11f-c3d08f310857",
        "handler": "bulk_payout",
        "details": "rpc error: code = Unknown desc = insufficient balance",
        "publicMessage": "Insufficient balance."
    }
}

HTTP Method : POST
API Endpoint :{{base_url}}/api/v1/payouts

{
    "currency": "NGN",
    "beneficiary_type": "single",
    "beneficiary_id": "2996ec06-4208-435b-8474-1528f0f66900",
    "amount": 10000,
    "remarks": "doing giveaway!"
}

Response

Initiate payout

{
    "status": 201,
    "data": {
        "business_id": "d04319d7-b3fb-478e-ade5-76cc5176e1dd",
        "cancel_reason": null,
        "completed_at": null,
        "count": 1,
        "created_at": "2024-04-18T16:12:40.82579046Z",
        "currency": "NGN",
        "fee": {
            "currency": "NGN",
            "symbol": "₦",
            "amount": 0
        },
        "is_recurring": false,
        "payout_type": "single",
        "remarks": "doing giveaway!",
        "status": "initiated",
        "total_amount": 10000,
        "updated_at": "2024-04-18T16:12:40.844577168Z"
    },
    "message": "Payout initiated successfully!",
    "error": null
}

curl --location 'https://sandbox-api.ovalfi-app.com/api/v1/payouts' \
--header 'Authorization: Bearer eyJidXNpbmVzc0lEIjoiYmEwY2E1NGMtZjRkYi00NDU5LWE4MDYtOTZkYzA3NWIzZjlkIiwidXNlcklEIjoiM2E5NjhiOWYtMzU5MC00ODZhLWE1MTMtYzg2MzkzZjZmYWI4Iiwia2V5IjoiaGFsZWVtYWgifQ==' \
--header 'Signature: 8042e424f924a236e9c8b4c6a76991ffeee24328d39cbb8a31d16cbca9948bf2' \
--form 'document=@"b079-80-f/Sample+NGN+Bulk+Payout+Instruction+++Bank+Codes (2).xlsx"' \
--form 'currency="NGN"' \
--form 'remarks="External API"'

Response

{
    "status": 201,
    "data": {
        "requestID": "f1f18f0f-0a38-4d16-bf6e-6f9c4fc5bcdb",
        "id": "26fdc99d-92f1-4b7d-9c84-9845abdd0c46",
        "business_id": "d04319d7-b3fb-478e-ade5-76cc5176e1dd",
        "status": "initiated",
        "count": 5,
        "currency": "NGN",
        "total_amount": 95020,
        "fee": {
            "currency": "NGN",
            "symbol": "₦",
            "amount": 0
        },
        "remarks": "External API",
        "cancel_reason": null,
        "completed_at": null,
        "created_at": "2023-06-19T14:13:47.437928208Z",
        "updated_at": "2023-06-19T14:13:47.438303583Z"
    },
    "message": "payout initiated successfully!",
    "error": null

🚧Restrictions

Initiate payout

🚧
Restrictions