--- title: "Add an external account" --- You must add any account not created with Gravv as an [external account](/platform/accounts/overview#external-accounts). To transfer funds to an external account, first use the recipient’s details to [create a customer](/getting-started/your-first-gravv-integration#create-a-customer). Then use the [Add an external account](/api-reference/external-accounts/post-v1-external-accounts) endpoint with the recipient's customer id to link the recipient to their bank account. You can add an external account for either [external transfers](/platform/transfers/external-transfers) or [international transfers](/platform/transfers/international-transfers). ## Add an external account for external transfers Use the recipient's bank account details and customer id to add an external account for external transfers: ```bash title="add an external account for external transfers request" curl --request POST \ --url https://api.gravv.xyz/v1/external-accounts \ --header 'Api-Key: ' \ --header 'Idempotency-Key: 979879887678789_attempt_1' \ --header 'content-type: application/json' \ --data ' { "payee_type": "ach_wire", "account_number": "4401682860", "account_name": "Amina Bello", "bank_name": "Example Community Bank", "currency": "USD", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "routing_number": "101019644", "account_owner_type": "individual", "account_type": "savings", "address": { "address_line1": "1800 N Pole St, Orlando, FL 32801", "state": "US-FL", "country": "US", "postal_code": "32801", "city": "Orlando" } } ' ``` You will get a response showing the recipient's bank account details and an external account id. Use the external account id for your external transfers: ```json title="add an external account for external transfers response" { "data": { "account_name": "Amina Bello", "account_number": "4401682860", "account_owner_type": "individual", "address": { "address_line1": "1800 N Pole St, Orlando, FL 32801", "address_line2": null, "city": "Orlando", "country": "US", "postal_code": "32801", "state": "US-FL" }, "currency": "USD", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "date_created": "2025-08-29T12:16:15.019149Z", "iban": null, "id": "e0c0d076-fd86-4739-b26d-527ab83ab033", "institution_country_iso_code": null, "institution_id": null, "institution_name": "Example Community Bank", "institution_type": null, "payee_type": "ach_wire", "routing_number": "101019644" }, "error": null } ``` ## Add an external account for international transfers For international transfers, you can add two types of global recipients: * **Global bank account recipient:** For sending funds to traditional bank accounts * **Global mobile money recipient:** For sending funds to mobile money accounts Both types follow the same setup process but use different account identifiers. ### Get the institution ID First, check [Supported countries](/getting-started/payments-and-supported-countries#supported-countries) to confirm that Gravv supports international transfers in the recipient's country. If Gravv supports the country, call the [Get external account institutions](/api-reference/external-accounts/get-v1-external-accounts-institutions) endpoint to fetch the institution id. Include the country’s ISO code in the query parameters: ```bash title="get external account institutions request" curl --request GET \ --url 'https://api.gravv.xyz/v1/external-accounts/institutions?country_iso_code=' \ --header 'Api-Key: ' \ --header 'accept: application/json' ``` The response returns both bank and Mobile Money institutions. Note the `account_number_type` field to identify the institution type. Copy the institution id from the response: ```json title="get external account institutions response" { "data": { "items": [ { "account_number_type": "bank_account_number", "country_iso_code": "NG", "currency": "NGN", "id": "279f86b7-2d03-48f4-aa27-3766de250099", "max_amount": 10000, "min_amount": 1, "name": "Stanbic IBTC Bank PLC" }, { "account_number_type": "bank_account_number", "country_iso_code": "NG", "currency": "NGN", "id": "c0cb83fa-8116-4744-8bc8-0c1cba405400", "max_amount": 10000, "min_amount": 1, "name": "Access Bank PLC" } ], "items_per_page": 10, "page": 1, "total_pages": 3 }, "error": null } ``` ### Add a global bank account recipient Use the recipient's bank account details, customer id, and the institution id to create a global bank account recipient: ```bash title="add a global bank account request" curl --request POST \ --url https://api.gravv.xyz/v1/external-accounts \ --header 'Api-Key: ' \ --header 'Idempotency-Key: 979879887678789_attempt_1' \ --header 'content-type: application/json' \ --data ' { "payee_type": "bank_account", "currency": "NGN", "account_number": "4401682860", "account_name": "Amina Bello", "bank_name": "Access Bank", "institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db" } ' ``` You will get a response showing the recipient's bank account details and an external account id: ```json title="add a global bank account response" { "data": { "account_name": "Amina Bello", "account_number": "4401682860", "address": null, "currency": "NGN", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "date_created": "2025-10-10T11:14:37.921052Z", "iban": null, "id": "74943275-6874-41b4-bd71-13d6cf5ed802", "institution_country_iso_code": "NG", "institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400", "institution_name": "Access Bank PLC", "institution_type": "bank", "payee_type": "bank_account", "routing_number": null }, "error": null } ``` ### Add a global Mobile Money recipient Use the recipient's Mobile Money account details, customer id, and the institution id for the Mobile Money provider to create a global Mobile Money recipient. For mobile money, the `account_number` field should contain the phone number: ```bash title="add a global Mobile Number request" curl --request POST \ --url https://api.gravv.xyz/v1/external-accounts \ --header 'Api-Key: ' \ --header 'Idempotency-Key: 979879887678789_attempt_1' \ --header 'content-type: application/json' \ --data ' { "payee_type": "mobile_money", "phone_number": "+233241234567", "account_name": "Kwame Mensah", "bank_name": "MTN Mobile Money", "currency": "GHS", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "institution_id": "5c8d94fb-a927-5fed-b19d-1454c8f142a9" } ' ``` You will get a response showing the recipient's mobile money account details and an external account id: ```json title="add a global Mobile Number response" { "data": { "account_name": "Kwame Mensah", "phone_number": "+233241234567", "account_owner_type": null, "address": null, "currency": "GHS", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "date_created": "2025-10-10T11:14:37.921052Z", "iban": null, "id": "8f2a9c65-3d4e-4b2f-a891-6e5d7c8f9a01", "institution_country_iso_code": "GH", "institution_id": "5c8d94fb-a927-5fed-b19d-1454c8f142a9", "institution_name": "MTN Mobile Money", "institution_type": "mobile_money", "payee_type": "mobile_money", "routing_number": null }, "error": null } ``` ### Add a SEPA recipient For SEPA transfers, use the recipient's IBAN, address, customer id, and account owner type. SEPA recipients don't require an institution ID: ```bash title="add a SEPA recipient request" curl --request POST \ --url https://api.gravv.xyz/v1/external-accounts \ --header 'Api-Key: ' \ --header 'Idempotency-Key: 979879887678789_attempt_1' \ --header 'content-type: application/json' \ --data ' { "payee_type": "sepa", "account_owner_type": "individual", "iban": "DE89370400440532013000", "account_name": "Anna Schmidt", "bank_name": "Deutsche Bank", "currency": "EUR", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "address": { "address_line1": "Unter den Linden 13", "city": "Berlin", "postal_code": "10117", "country": "DE" } } ' ``` You will get a response showing the recipient's SEPA account details and an external account id: ```json title="add a SEPA recipient response" { "data": { "account_name": "Anna Schmidt", "account_number": null, "account_owner_type": "individual", "address": { "address_line1": "Unter den Linden 13", "address_line2": null, "city": "Berlin", "country": "DE", "postal_code": "10117", "state": null }, "currency": "EUR", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "date_created": "2025-11-26T10:15:30.921052Z", "iban": "DE89370400440532013000", "id": "9d3f1b2e-5c4a-4e8f-b9a2-7c6e8d9f0b12", "institution_country_iso_code": null, "institution_id": null, "institution_name": "Deutsche Bank", "institution_type": null, "payee_type": "sepa", "routing_number": null }, "error": null } ``` Use the external account id from any of these responses for your [international transfers](/platform/transfers/international-transfers). ### Add a SWIFT recipient Use SWIFT transfers for international USD transfers outside the US and SEPA zone. SWIFT recipients require the recipient's bank account details, Bank Identifier Code (BIC), address, customer id, and account owner type: ```bash title="add a SWIFT recipient request" curl --request POST \ --url https://api.gravv.xyz/v1/external-accounts \ --header 'Api-Key: ' \ --header 'Idempotency-Key: 979879887678789_attempt_1' \ --header 'content-type: application/json' \ --data ' { "payee_type": "swift", "account_owner_type": "individual", "account_number": "1245909283", "account_name": "Amina Bello", "bank_name": "Guaranty Trust Bank (GTBank)", "bic": "NG2893A", "currency": "USD", "customer_id": "373556ec-74e5-4cde-909c-b94d864915db", "address": { "address_line1": "15 Admiralty Way, Lekki Phase 1", "city": "Lekki", "state": "Lagos", "postal_code": "105102", "country": "NG" } } ' ```