Bulk payouts

curl -o bulk-template.csv "$MG_BASE_URL/payment-service/api/v1/transfer/bulk-transfer-template?format=csv" \
  -H "mp-api-key: $MG_API_KEY"

Leave out format=csv to get the Excel workbook. Only its Transfer Entries sheet is read. The Instruction sheet explains each column; the other sheets list bank names with BICs, countries and currencies for the drop-downs.

One transfer per row. Keep the header row exactly as in the template (same spelling, upper case and spaces). Empty rows are skipped.

A complete CSV file with two NGN rows looks like this:

AMOUNT,NARRATION,BENEFICIARY BANK,BENEFICIARY BANK BIC OR CODE,BENEFICIARY BANK ADDRESS,BENEFICIARY ACCOUNT NAME,BENEFICIARY ACCOUNT NUMBER,BENEFICIARY NAME,BENEFICIARY ADDRESS,BENEFICIARY CITY,BENEFICIARY STATE,BENEFICIARY COUNTRY,BENEFICIARY EMAIL ADDRESS,BENEFICIARY PHONE NUMBER,INTERMEDIARY BANK,INTERMEDIARY BANK COUNTRY,CHARGE TYPE,PAYMENT METHOD
400000,October salary,Guaranty Trust Bank,058,"635 Akin Adesola Street, Lagos",ADA OKAFOR,0123456789,Ada Okafor,12 Marina Road,Lagos,Lagos,NGA,ada.okafor@example.com,2348012345678,,,,NIP
250000,October salary,Guaranty Trust Bank,058,"635 Akin Adesola Street, Lagos",TUNDE BELLO,0234567891,Tunde Bello,3 Allen Avenue,Ikeja,Lagos,NGA,tunde.bello@example.com,,,,,NIP

A SWIFT row (in a USD file) fills the last four columns, for example …,Citibank N.A.-CITIUS33XXX,USA,SHA,SWIFT. Its account number must still be digits only.

Put a value in quotes when it contains a comma, as in the bank address above.

Send the file as the multipart part file, with its content type set. Many clients send application/octet-stream, which is refused. Use text/csv for CSV and application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for .xlsx.

curl -X POST "$MG_BASE_URL/payment-service/api/v1/transfer/bulk-transfer/preview" \
  -H "mp-api-key: $MG_API_KEY" \
  -F "file=@bulk-template.csv;type=text/csv" \
  -F "onBehalfOf=$MG_CLIENT_ID" \
  -F "sourceAccountNumber=$MG_ACCOUNT_NUMBER" \
  -F "sourceCurrencyIso3Code=NGN"

{
  "message": "Successful",
  "previewId": "2f1c0b9a-8d7e-4f6a-9b5c-3e2d1c0b9a8d",
  "batchId": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "summary": { "totalAmount": 650000, "totalFees": 100, "transferCount": 2, "requiresApproval": false },
  "rows": [
    { "rowNumber": 2, "narration": "October salary", "amount": 400000, "currency": "NGN", "errors": [] },
    { "rowNumber": 3, "narration": "October salary", "amount": 250000, "currency": "NGN", "errors": [] }
  ]
}

Nothing is paid yet. Two kinds of problems come back:

• File problems (a missing column, an empty mandatory cell, a wrong type, an unknown purpose code) return 400 with the first problem only. Fix it and upload again.
• Row problems come back in rows[].errors with field and message, for example beneficiaryEmailAddress "Beneficiary email address is invalid." or beneficiaryDetails "Beneficiary lookup failed.". rowNumber is the line in your file, counting the header as line 1.

Show summary.totalAmount + summary.totalFees to your user for confirmation; that's what the rows will debit. summary.requiresApproval: true means the rows will wait for an approver in your business.

During the preview, each beneficiary is looked up at their bank, and beneficiaries you haven't paid before are saved to your beneficiary list.

A preview with any row error can't be committed. To fix them:

1. List the rows that have errors:

curl -s -X POST "$MG_BASE_URL/payment-service/api/v1/transfer/bulk-transfer/preview" \
  -H "mp-api-key: $MG_API_KEY" \
  -F "file=@bulk-template.csv;type=text/csv" \
  -F "onBehalfOf=$MG_CLIENT_ID" \
  -F "sourceAccountNumber=$MG_ACCOUNT_NUMBER" \
  -F "sourceCurrencyIso3Code=NGN" \
  | jq '.rows[] | select(.errors | length > 0) | {rowNumber, errors}'

{
  "rowNumber": 3,
  "errors": [
    { "field": "beneficiaryEmailAddress", "message": "Beneficiary email address is invalid." },
    { "field": "beneficiaryDetails", "message": "Beneficiary lookup failed.", "code": "beneficiaryLookupFailed" }
  ]
}

2. For each row, correct the cell that field points to (rowNumber is the line in your file, header = line 1):

3. Or remove the rows you can't fix yet, and pay them later in another file.
4. Preview the corrected file again. You get a new previewId; commit that one. Previews you don't commit expire after 30 minutes and are never paid.

curl -X POST "$MG_BASE_URL/payment-service/api/v1/transfer/bulk-transfer/commit" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "previewId": "2f1c0b9a-8d7e-4f6a-9b5c-3e2d1c0b9a8d", "comment": "October payroll" }'

{
  "message": "Successful",
  "batchReference": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "processing": 2,
  "failed": 0,
  "responseCode": "01",
  "responseMessage": "Transfers sent successfully"
}

Commit within 30 minutes of the preview. The balance check (total plus fees) happens now. A preview can be committed only once: after a successful commit, a second one returns "Invalid transaction…" and creates nothing.

Every row is an ordinary transfer with its own uniqueRequestId (generated by Multigate), transactionId, status and webhook. The webhook doesn't carry the batchId, so right after the commit, list the rows and store each row's IDs against your own records:

curl -s "$MG_BASE_URL/payment-service/api/v1/transaction/report?batchId=6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d&pageSize=100&pageNumber=1" \
  -H "mp-api-key: $MG_API_KEY" \
  | jq '{totalPages, rows: [.data[] | {uniqueRequestId, transactionId, status, amount, account: .beneficiaryDetails.accountNumber, reference}]}'

• Match each row to your file by beneficiary account number and amount (reference is the row's NARRATION, shortened).
• Pages hold at most 100 rows: increase pageNumber until you reach totalPages.
• Then handle each row's transfer_completed / transfer_failed webhook by its uniqueRequestId, as in Payouts › After you send, and poll rows that stay non-final with the same batchId query.

Users with the approve payment permission can also see the batch with its totals and all rows with Get a bulk transfer.