Skip to content

Get started

This guide shows everything required to run Transfer SNS end to end for Wave.

By the end of this guide, you will have:

  • Environment access and credentials
  • A configured webhook endpoint
  • An active External Account (Recipient) to use as transfer destination
  • A working POST /v1/transfer/sns flow

1. Prepare access

  1. Sign in to your Gravv Dashboard.
  2. Confirm access to your production API credentials.
  3. Add your outbound IPs to the allowlist (Manage → Configure → IP Access List) if your tenant enforces IP restrictions.

For environment URLs and mode separation, see Environments.

2. Obtain API credentials

  1. In Dashboard, open Manage → Configure → API Keys.
  2. Copy your server-side secret key.
  3. Use it as Api-Key on API requests.
  4. Generate a unique Idempotency-Key per transfer request.
  5. Copy your customer_id from the same Manage → API Keys section for transfer payloads that require it.

For request header details, see Authentication.

3. Configure webhooks

Transfer SNS is asynchronous. Final outcomes are delivered by webhook events.

  1. In Dashboard, open Webhooks.
  2. Create your webhook endpoint URL.
  3. Generate and store your webhook secret key.
  4. Implement signature verification before processing payloads.

For payload format and verification, see Webhooks.

4. Create an External Account (Recipient) destination

Create an External Account (Recipient) with POST /v1/external-accounts. Supported payout destination types are:

  • bank_account
  • mobile_money

Depending on your tenant approval policy, a newly created External Account (Recipient) can be parked in waiting_approval until maker-checker approval is completed. An External Account (Recipient) can only be used for Transfer SNS when its status is active.

5. Confirm source account

POST /v1/transfer/sns requires source.id (internal account) and destination.id (External Account/Recipient).

Use the source account provisioned for your business by Gravv. If you do not have it, request it from your Gravv onboarding/contact team.

6. Initiate Transfer SNS

Send POST /v1/transfer/sns with:

  • source.source_type = internal_account
  • source.id = <your source account id>
  • destination.destination_type = external_account
  • destination.id = <active external account recipient id>
  • amount as a decimal string (for example "100.00")
  • Api-Key and Idempotency-Key request headers

The request returns an accepted transfer record (reference, transfer_status), then webhook events drive the final lifecycle.

See Transfer SNS guide for full request/response and lifecycle behavior.