• Introduction
• Authentication
• Sender details
• Recipient details
• Collection details
• Creating the transaction
• Waiting for the transaction to finish
• Getting the transaction status manually
• Schedule the onboarding call

Introduction

In this example we’ll go through all of the steps and give examples on what you’ll need to do to implement a call to collect funds from customers into your internal balance. Once you’ve read through this guide you’ll know everything that is required by us for you to use our collection system.

Let’s assume that you would like to obtain funds from one of your Ghanan customer, Jane Doe. You have already fully KYC’d her, as she is a recurring user on your site. Her user ID in your system is Sender:GH:9547. She creates an order in your system for which she is charged 50 GHS that she’d like to pay using her mobile wallet. For this transaction let’s assume the transaction created in your system has an ID of Collection:GHS:91475.

Once you have the details collected on your end, you can then initiate the transaction in our system. This example will guide you through the details you need to set and what calls you need to make. Since the easiest way to access our system is through our SDKs this guide is mainly aimed at users of our SDKs.

Authentication

First thing is that you’ll need to authenticate to use our site. You can get your API key and secret by logging in to the TransferZero developer portal.

Once you obtain your api key and secret you’ll need to set up your environment with them:

Configuration configuration = new Configuration();
configuration.ApiKey = "<key>";
configuration.ApiSecret = "<secret>";
configuration.BasePath = "https://api-sandbox.transferzero.com/v1";

Dim configuration As Configuration = New Configuration()
configuration.ApiKey = "KEY"
configuration.ApiSecret = "SECRET"
configuration.BasePath = "https://api-sandbox.transferzero.com/v1"

ApiClient apiClient = new ApiClient();
apiClient.setApiKey("<key>");
apiClient.setApiSecret("<secret>");
apiClient.setBasePath("https://api-sandbox.transferzero.com/v1");

const apiClient = new ApiClient();
apiClient.apiKey = '<key>';
apiClient.apiSecret = '<secret>';
apiClient.basePath = 'https://api-sandbox.transferzero.com/v1';

TransferZero\Configuration::getDefaultConfiguration()
    ->setHost("https://api-sandbox.transferzero.com/v1")
    ->setApiKey("<key>")
    ->setApiSecret("<secret>");

TransferZero.configure do |config|
    config.api_key = '<key>'
    config.api_secret = '<secret>'
    config.host = 'https://api-sandbox.transferzero.com/v1'
end

Sender details

Next step is setting up the sender details. Generally you’ll need to send us the following information for every sender:

• name
• country
• phone number
• address
• birth date
• email address

You should also send us the ID you use in your local system to link to this sender, in this example Sender:GH:9547. By doing so you’ll be able to handle senders much easier in our system.

{
    "first_name": "Jane",
    "last_name": "Doe",

    "phone_country": "GH",
    "phone_number": "+233301234567", // E.164 international format

    "country": "GH",
    "city": "Accra",
    "street": "1 La Rd",
    "postal_code": "GA100",
    "address_description": "",

    "birth_date": "1974-12-24",

    // you can usually use your company's contact email address here
    "email": "[email protected]",

    "external_id": "Sender:GH:9547",

    // these fields are mandatory, but you can usually leave them with the following default values:
    "documents": [ ],
    "ip": "127.0.0.1",
    "metadata": {}
}

Sender sender = new Sender(
  firstName: "Jane",
  lastName: "Doe",

  phoneCountry: "GH",
  phoneNumber: "+233301234567", // E.164 international format

  country: "GH",
  city: "Accra",
  street: "1 La Rd",
  postalCode: "GA100",
  addressDescription: "",

  birthDate: DateTime.Parse("1974-12-24"),

// you can usually use your company's contact email address here
  email: "[email protected]",

  externalId: "Sender:GH:9547",

// you'll need to set these fields but usually you can leave them the default
  ip: "127.0.0.1",
  documents: new List<Document>());

Dim sender as Sender = New Sender(
  firstName:="Jane",
  lastName:="Doe",

  phoneCountry:="GH",
  phoneNumber:="+233301234567", ' E.164 international format

  country:="GH",
  city:="Accra",
  street:="1 La Rd",
  postalCode:="GA100",
  addressDescription:="",

  birthDate:=DateTime.Parse("1974-12-24"),

' you can usually use your company's contact email address here
  email:="[email protected]",

  externalId:="Sender:GH:9547",

' you'll need to set these fields but usually you can leave them the default
  ip:="127.0.0.1",
  documents:=New List(Of Document)()))

Sender sender = new Sender();
sender.setFirstName("Jane");
sender.setLastName("Doe");

sender.setPhoneCountry("GH");
sender.setPhoneNumber("+233301234567"); // E.164 international format

sender.setCountry("GH");
sender.setCity("Accra");
sender.setStreet("1 La Rd");
sender.setPostalCode("GA100");
sender.setAddressDescription("");

sender.setBirthDate(LocalDate.parse("1974-12-24"));

// you can usually use your company's contact email address here
sender.setEmail("[email protected]");

sender.setExternalId("Sender:GH:9547");

// you'll need to set these fields but usually you can leave them the default
sender.setIp("127.0.0.1");
sender.setDocuments(new ArrayList<>());

const sender = new TransferZeroSdk.Sender();
sender.first_name = "Jane";
sender.last_name = "Doe";

sender.phone_country = "GH";
sender.phone_number = "+233301234567"; // E.164 international format

sender.country = "GH";
sender.city = "Accra";
sender.street = "1 La Rd";
sender.postal_code = "GA100";
sender.address_description = "";

sender.birth_date = "1974-12-24";

// you can usually use your company's contact email address here
sender.email = "[email protected]";

sender.external_id = "Sender:GH:9547";

// you'll need to set these fields but usually you can leave them the default
sender.ip = "127.0.0.1";
sender.documents = [];

$sender = new Sender();
$sender->setFirstName("Jane");
$sender->setLastName("Doe");

$sender->setPhoneCountry("GH");
$sender->setPhoneNumber("+233301234567"); // E.164 international format

$sender->setCountry("GH");
$sender->setCity("Accra");
$sender->setStreet("1 La Rd");
$sender->setPostalCode("GA100");
$sender->setAddressDescription("");

$sender->setBirthDate("1974-12-24");

// you can usually use your company's contact email address here
$sender->setEmail("[email protected]");

$sender->setExternalId("Sender:GH:9547");

// you'll need to set these fields but usually you can leave them the default
$sender->setIp("127.0.0.1");
$sender->setDocuments([]);

sender = TransferZero::Sender.new
sender.first_name = "Jane"
sender.last_name = "Doe"

sender.phone_country = "GH"
sender.phone_number = "+233301234567" # E.164 international format

sender.country = "GH"
sender.city = "Accra"
sender.street = "1 La Rd"
sender.postal_code = "GA100"
sender.address_description = ""

sender.birth_date = "1974-12-24"

# you can usually use your company's contact email address here
sender.email = "[email protected]"

sender.external_id = "Sender:GH:9547"

# you'll need to set these fields but usually you can leave them the default
sender.ip = "127.0.0.1"
sender.documents = []

Recipient details

Once you have the sender let’s set up the recipient as well. For collections you usually collect the funds in your internal wallet. Let’s assume you wish to collect the funds in USD (we’ll calculate the exchange rate).

{
    "requested_amount": "50",
    "requested_currency": "GHS",
    "payout_method": {
        "type": "USD::Balance",
        "details": {
            "reference": "Collection:GHS:91475"
        }
    }
}

PayoutMethodDetails details = new PayoutMethodDetails(
  reference: "Collection:GHS:91476");

PayoutMethod payout = new PayoutMethod(
  type: "USD::Balance",
  details: details);

Recipient recipient = new Recipient(
  requestedAmount: 50,
  requestedCurrency: "GHS",
  payoutMethod: payout);

Dim details as PayoutMethodDetails = New PayoutMethodDetails(
  reference:="Collection:GHS:91476")

Dim payout as PayoutMethod = New PayoutMethod(
  type:="USD::Balance",
  details:=details)

Dim recipient as Recipient = New Recipient(
  requestedAmount:=50,
  requestedCurrency:="GHS",
  payoutMethod:=payout)

PayoutMethodDetails details = new PayoutMethodDetails();
details.setReference("Collection:GHS:91476");

PayoutMethod payout = new PayoutMethod();
payout.setType("USD::Balance");
payout.setDetails(details);

Recipient recipient = new Recipient();
recipient.setRequestedAmount(new BigDecimal("50"));
recipient.setRequestedCurrency("GHS");
recipient.setPayoutMethod(payout);

const details = new TransferZeroSdk.PayoutMethodDetails();
details.reference = "Collection:GHS:91476";

const payout = new TransferZeroSdk.PayoutMethod();
payout.type = "USD::Balance";
payout.details = details;

const recipient = new TransferZeroSdk.Recipient();
recipient.requested_amount = 50;
recipient.requested_currency = "GHS";
recipient.payout_method = payout;

$details = new PayoutMethodDetails();
$details->setReference("Collection:GHS:91476");

$payout = new PayoutMethod();
$payout->setType("USD::Balance");
$payout->setDetails($details);

$recipient = new Recipient();
$recipient->setRequestedAmount(50);
$recipient->setRequestedCurrency("GHS");
$recipient->setPayoutMethod($payout);

details = TransferZero::PayoutMethodDetails.new
details.reference = "Collection:GHS:91476"

payout = TransferZero::PayoutMethod.new
payout.type = "USD::Balance"
payout.details = details

recipient = TransferZero::Recipient.new
recipient.requested_amount = 50
recipient.requested_currency = "GHS"
recipient.payout_method = payout

Collection details

Finally we need to tie the sender and recipient together into a transaction. We also need to set up the collection settings as well. Since we’re going to use GHS mobile collection, we’ll have to provide the sender’s phone number.

{
    "sender": {
        // sender details from the previous section
    },
    "recipients": [{
        // recipient details from the previous section
    }],
    "payin_methods": [{
        "type": "GHS::Mobile", 
        "ux_flow": "ussd_popup",
        "in_details": {
            "phone_number": "+2339999999", // E.164 international format
            "mobile_provider": "vodafone" // Mandatory. One of 'airtel', 'tigo', 'mtn', 'vodafone'
        }
    }],
    "input_currency": "GHS",
    "external_id": "Transaction:GHS:91475",
    "metadata": {}
}

PayinMethodDetails details = new PayinMethodDetails(
  phoneNumber: "+2339999999", // E.164 international format
  mobileProvider: PayoutMethodMobileProviderEnum.VODAFONE);

PayinMethod method = new PayinMethod(
  type: "GHS::Mobile",
  uxFlow: PayinMethodUxFlow.USSD_POPUP,
  inDetails: details);

Transaction transaction = new Transaction(
  sender: sender,
  recipients: new List<Recipient>() { recipient },
  payinMethods: new List<PayinMethod>() { method },
  inputCurrency: "GHS",
  externalId: "Transaction:GHS:91475");

Dim details as PayinMethodDetails = New PayinMethodDetails(
  phoneNumber:="+2339999999", ' E.164 international format
  mobileProvider:=PayoutMethodMobileProviderEnum.VODAFONE)

Dim method as PayinMethod = New PayinMethod(
  type:="GHS::Mobile",
  uxFlow:=PayinMethodUxFlow.USSD_POPUP,
  inDetails:=details)

Dim transaction as Transaction = New Transaction(
  sender:=sender,
  recipients:=New List(Of Recipient)() From { recipient },
  payinMethods:=New List(Of PayinMethod)() From { method },
  inputCurrency:="GHS",
  externalId:="Transaction:GHS:91475")

PayinMethodDetails details = new PayinMethodDetails();
details.setPhoneNumber("+2339999999"); // E.164 international format
details.setMobileProvider(PayoutMethodMobileProviderEnum.VODAFONE);

PayinMethod method = new PayinMethod();
method.setType("GHS::Mobile");
method.setUxFlow(PayinMethodUxFlow.USSD_POPUP);
method.setInDetails(details);

Transaction transaction = new Transaction();
transaction.setSender(sender);
transaction.addRecipientsItem(recipient);
transaction.addPayinMethodsItem(method);
transaction.setInputCurrency("GHS");
transaction.setExternalId("Transaction:GHS:91475");

const details = new TransferZeroSdk.PayinMethodDetails();
details.phone_number = "+2339999999"; // E.164 international format
details.mobile_provider = "vodafone";

const method = new TransferZeroSdk.PayinMethod();
method.type = "GHS::Mobile";
method.ux_flow = "ussd_popup";
method.in_details = details;

const transaction = new TransferZeroSdk.Transaction();
transaction.sender = sender;
transaction.recipients = [recipient];
transaction.payin_methods = [method];
transaction.input_currency = "GHS";
transaction.external_id = "Transaction:GHS:91475";

$details = new PayinMethodDetails();
$details->setPhoneNumber("+2339999999"); // E.164 international format
$details->setMobileProvider("vodafone");

$method = new PayinMethod();
$method->setType("GHS::Mobile");
$method->setUxFlow("ussd_popup");
$method->setInDetails($details);

$transaction = new Transaction();
$transaction->setSender($sender);
$transaction->setRecipients([recipient]);
$transaction->setPayinMethods([method]);
$transaction->setInputCurrency("GHS");
$transaction->setExternalId("Transaction:GHS:91475");

details = TransferZero::PayinMethodDetails.new
details.phone_number = "+2339999999" # E.164 international format
details.mobile_provider = "vodafone"

method = TransferZero::PayinMethod.new
method.type = "GHS::Mobile"
method.ux_flow = "ussd_popup"
method.in_details = details

transaction = TransferZero::Transaction.new
transaction.sender = sender
transaction.recipients = [recipient]
transaction.payin_methods = [method]
transaction.input_currency = "GHS"
transaction.external_id = "Transaction:GHS:91475"

Creating the transaction

Now that we have generated the objects, we’ll need to call the endpoint. Note that once the transaction is created the sender will receive a prompt on their phone to pay in the funds

POST /v1/transactions

{
    "transaction": {
        // full transaction details from the previous section
    }
}

TransactionRequest request = new TransactionRequest(
  transaction: transaction);

TransactionsApi api = new TransactionsApi(configuration);

try {
  TransactionResponse response = api.PostTransactions(request);
} catch (ApiException e) {
  if (e.IsValidationError)
    TransactionResponse response = e.ParseObject<TransactionResponse>();
    // Process validation error
  }
  throw e;
}

Dim request as TransactionRequest = New TransactionRequest(
  transaction:=transaction)

Dim api as TransactionsApi = New TransactionsApi(configuration)

Try
  Dim response as TransactionResponse = api.PostTransactions(request)
Catch e As ApiException
  If e.IsValidationError Then
    Dim response as TransactionResponse = e.ParseObject(Of TransactionResponse)()
    ' Process validation error
  End If
  Throw e
End Try

TransactionRequest request = new TransactionRequest();
request.setTransaction(transaction);

TransactionsApi api = new TransactionsApi(apiClient);

try {
  TransactionResponse response = api.postTransactions(request);
} catch (ApiException e) {
  if (e.isValidationError()) {
    TransactionResponse response = e.getResponseObject(TransactionResponse.class);
    // Process validation error
  }
  throw e;
};

const request = new TransferZeroSdk.TransactionRequest();
request.transaction = transaction;

const api = new TransferZeroSdk.TransactionsApi(apiClient);

try {
  const response = await api.postTransactions(request);
} catch (e) {
  if (e.isValidationError) {
    const response = e.getResponseObject();
    // Process validation error
  }
  throw e;
}

$request = new TransactionRequest();
$request->setTransaction($transaction);

$api = new TransactionsApi();

try {
  $response = api->postTransactions($request);
} catch (ApiException $e) {
  if ($e->isValidationError()) {
    $response = $e->getResponseObject();
    // Process validation error
  }
  throw $e;
}

request = TransferZero::TransactionRequest.new
request.transaction = transaction

api = TransferZero::TransactionsApi.new

begin
  response = api.post_transactions(request)
rescue TransferZero::ApiError => e
  if e.validation_error
    response = e.response_object("TransactionResponse")
    # Process validation error
  end
  raise e
end

Waiting for the transaction to finish

Once the transaction is created, the customer has one hour to fulfill the collection requirements. After this initial period has elapsed the transaction will be cancelled and it will not accept funds received anymore. In order to let you know when the customer has fulfilled the collection and paid in the funds we will send out a notification to your registered webhook address.

To set up webhooks you can use the TransferZero developer portal. We will always call the endpoint you set up here using POST, and the request will always contain the same authentication headers you’ll need to use to call our APIs, so you can use them to validate that the request is coming from us.

string webhookContent = "{ full body of the webhook }";
string url = "<full url of the webhook>";

Dictionary<string, string> headers = new Dictionary<string, string>();
headers.Add("Authorization-Nonce", "<nonce from the webhook headers>");
headers.Add("Authorization-Signature", "<signature from the webhook headers>");
headers.Add("Authorization-Key", "<key from the webhook headers>");

if (configuration.ValidWebhookRequest(url, webhookContent, headers))
{
    Webhook webhook = configuration.ParseString<Webhook>(webhookContent);
    if (webhook.Event.StartsWith("payin_method")) {
        PayinMethodWebhook payinMethodWebhook = configuration.ParseString<PayinMethodWebhook>(webhookContent);
        string externalId = payinMethodWebhook.Object.ExternalId;
        if (webhook.Event == "payin_method.error"){
            // handle collection attempt has failed.
        }           
    } else if (webhook.Event.StartsWith("transaction")) {
        TransactionWebhook transactionWebhook = configuration.ParseString<TransactionWebhook>(webhookContent);
        Guid transactionId = transactionWebhook.Object.Id;
        string externalId = transactionWebhook.Object.ExternalId;
        if (webhook.Event == "transaction.paid_in") {
            // handle user has sent in the funds event
        } else if (webhook.Event == "transaction.paid_out") {
            // handle transaction has finished processing and the funds are in the internal balance
        } else if (webhook.Event == "transaction.canceled") {
            // handle transaction has not been funded by the customer event
        }
    } else if (webhook.Event.StartsWith("sender")) {
        SenderWebhook senderWebhook = configuration.ParseString<SenderWebhook>(webhookContent);
        // handle sender events
    }
}

Dim webhookContent As String = "{ full body of the webhook }"
Dim url As String = "<full url of the webhook>"

Dim headers As Dictionary(Of String, String) = New Dictionary(Of String, String)()
headers.Add("Authorization-Nonce", "<nonce from webhook headers>")
headers.Add("Authorization-Signature", "<signature from webhook headers>")
headers.Add("Authorization-Key", "<key from webhook headers>")

If configuration.ValidWebhookRequest(url, webhookContent, headers) Then
    Dim webhook As Webhook = configuration.ParseString(Of Webhook)(webhookContent)
    If webhook.[Event].StartsWith("payin_method") Then
        Dim payinMethodWebhook As PayinMethodWebhook = configuration.ParseString(Of PayinMethodWebhook)(webhookContent)
        Dim externalId As String = payinMethodWebhook.Object.ExternalId
        If webhook.[Event].Equals("payin_method.error") Then
          ' handle collection attempt has failed.
        End If        
    ElseIf webhook.[Event].StartsWith("transaction") Then
        Dim transactionWebhook As TransactionWebhook = configuration.ParseString(Of TransactionWebhook)(webhookContent)
        Dim transactionId As Guid = transactionWebhook.Object.Id
        Dim externalId As String = transactionWebhook.Object.ExternalId
        If webhook.[Event].Equals("transaction.paid_in") Then
          ' handle user has sent in the funds event
        ElseIf webhook.[Event].Equals("transaction.paid_out") Then
          ' handle transaction has finished processing and the funds are in the internal balance
        ElseIf webhook.[Event].Equals("transaction.canceled") Then
          ' handle transaction has not been funded by the customer event
        End If
    ElseIf webhook.[Event].StartsWith("sender") Then
        Dim senderWebhook As SenderWebhook = configuration.ParseString(Of SenderWebhook)(webhookContent)
        ' handle sender webhooks
    End If
End If

String webhookBody = "{ full body of the webhook }";
String webhookUrl = "<full url of the webhook>";

Map<String, String> webhookHeaders = new HashMap<String, String>();
webhookHeaders.put("Authorization-Nonce", "<nonce from webhook headers>");
webhookHeaders.put("Authorization-Key", "<key from webhook headers>");
webhookHeaders.put("Authorization-Signature", "<signature from webhook headers>");

if (apiClient.validateWebhookRequest(webhookUrl, webhookBody, webhookHeaders)) {
    Webhook webhook = apiClient.parseResponseString(webhookBody, Webhook.class);
    if (webhook.getEvent().startsWith("payin_method")) {
        PayinMethodWebhook payinMethodWebhook = apiClient.parseResponseString(webhookBody, PayinMethodWebhook.class);
        String externalId = payinMethodWebhook.getObject().getExternalId();
        
        if (webhook.getEvent().equals("payin_method.error")  {
          // handle collection attempt has failed.
        }
    } else if (webhook.getEvent().startsWith("transaction")) {
        TransactionWebhook transactionWebhook = apiClient.parseResponseString(webhookBody, TransactionWebhook.class);
        UUID transactionId = transactionWebhook.getObject().getId();
        String externalId = transactionWebhook.getObject().getExternalId();
        if (webhook.getEvent().equals("transaction.paid")) {
          // handle user has sent in the funds event
        } else if (webhook.getEvent().equals("transaction.refunded")) {
          // handle transaction has finished processing and the funds are in the internal balance
        } else if (webhook.getEvent().equals("transaction.refunded")) {
          // handle transaction has not been funded by the customer event
        }
    } else if (webhook.getEvent().startsWith("sender")) {
        SenderWebhook senderWebhook = apiClient.parseResponseString(webhookBody, SenderWebhook.class);
        // handle sender webhooks
    }
}

const webhookContent = `{ full body of the webhook }`;
const webhookUrl = "<full url of the webhook>";

const webhookHeader = {
  "Authorization-Nonce": "<nonce from webhook headers>",
  "Authorization-Key": "<key from webhook headers>",
  "Authorization-Signature": "<signature from webhook headers>"};

if (apiClient.validateRequest(webhookUrl, webhookContent, webhookHeader)) {
  const webhook = apiClient.parseResponseString(webhookContent,TransferZeroSdk.Webhook);
  if (webhook.event.startsWith('payin_method')) {
    const payinMethodWebhook = apiClient.parseResponseString(webhookContent, TransferZeroSdk.payinMethodWebhook);
    const externalId = payinMethodWebhook.object.external_id;

    if (webhook.event == "payin_method.error")  {
      // handle collection attempt has failed.
    }
  } else if (webhook.event.startsWith('transaction')) {
      const transactionWebhook = apiClient.parseResponseString(webhookContent, TransferZeroSdk.TransactionWebhook);
      const transactionId = transactionWebhook.object.id;
      const externalId = transactionWebhook.object.external_id;
      if (webhook.event == 'transaction.paid') {
          // handle user has sent in the funds event
      } else if (webhook.event == 'transaction.refunded') {
          // handle transaction has finished processing and the funds are in the internal balance
      } else if (webhook.event == 'transaction.refunded') {
          // handle transaction has not been funded by the customer event
      }
  } else if (webhook.event.startsWith('sender')) {
      const senderWebhook = apiClient.parseResponseString(webhookContent, TransferZeroSdk.SenderWebhook);
      // handle sender webhook
  }
}

$webhook_content = "{ full body of the webhook }";
$webhook_url = "<full url of the webhook>";

$webhook_headers = [
    "Authorization-Nonce" => "<nonce from the webhook headers>",
    "Authorization-Key" => "<key from the webhook headers>",
    "Authorization-Signature" => "<signature from the webhook headers>"];

if (new WebhooksApi()->validateWebhookRequest($webhook_url, $webhook_content, $webhook_headers)) {
    $webhook = new WebhooksApi()->parseResponseString($webhook_content, 'Webhook');
    if (strpos($webhook->getEvent(), 'payin_method') === 0) {
        $payinMethodWebhook = $webhooksApi->parseResponseString($webhook_content, 'PayinMethodWebhook');
        $externalId = $payinMethodWebhook->getObject()->getExternalId();

        if ($webhook->getEvent() == "payin_method.error")  {
          // handle collection attempt has failed.
        }
    } elseif (strpos($webhook->getEvent(), 'transaction') === 0) {
        $transactionWebhook = $webhooksApi->parseResponseString($webhook_content, 'TransactionWebhook');
        $transacionId = $transactionWebhook->getObject()->getId();
        $externalId = $transactionWebhook->getObject()->getExternalId();
        if ($webhook->getEvent() == 'transaction.paid') {
            // handle user has sent in the funds event
        } elseif ($webhook->getEvent() == 'transaction.refunded') {
            // handle transaction has finished processing and the funds are in the internal balance
        } elseif ($webhook->getEvent() == 'transaction.refunded') {
            // handle transaction has not been funded by the customer event
        }
    } elseif (strpos($webhook->getEvent(), 'sender') === 0) {
        $senderWebhook = $webhooksApi->parseResponseString($webhook_content, 'SenderWebhook');
        // handle sender webhook
    }
}

body = "{ full body of the webhook }"
webhook_url = "<full url of the webhook>"

headers = {
    "Authorization-Nonce": "<nonce from webhook headers>",
    "Authorization-Key": "<key from webhook headers>",
    "Authorization-Signature": "<signature from webhook headers>"}

if TransferZero::ApiClient.new.validate_webhook_request(webhook_url, body, headers)
  webhook = TransferZero::ApiClient.new.parse_response(body, "Webhook")
  if webhook['event'].start_with?('payin_method')
    payin_method_webhook = webhook_api.parse_response(body, 'PayinMethodWebhook')
    external_id = payin_method_webhook.object.external_id

    if webhook['event'] == "payin_method.error"
      # handle collection attempt has failed.
    end
  elsif webhook['event'].start_with?('transaction')
    transaction_webhook = webhook_api.parse_response(body, 'TransactionWebhook')
    transaction_id = transaction_webhook.object.id
    external_id = transaction_webhook.object.external_id
    if webhook['event'] == 'transaction.paid'
      # handle user has sent in the funds event
    elsif webhook['event'] == 'transaction.paid'
      # handle transaction has finished processing and the funds are in the internal balance
    elsif webhook['event'] == 'transaction.refunded'
      # handle transaction has not been funded by the customer event
    end
  elsif webhook['event'].start_with?('sender')
    sender_webhook = webhook_api.parse_response(body, 'SenderWebhook')
    # handle sender webhook
  end
end

For collections you will need to handle three major webhook events namely transaction.paid_in, transaction.paid_out and transaction.canceled. The first one will notify you if the customer has paid in the funds. The second one will notify you if the funds were then put into your internal balance (which usually happens right after the funds have been received). Finally the last event lets you know that we haven’t received the funds in time.

If you don’t do full KYC then you should also sign up for the sender.approved event which will notify you if a sender is approved and can start transacting, and the sender.rejected event which signals if there is a problem with the sender.

Getting the transaction status manually

While we prefer that you primarily use the webhook facility to get notified about state changes, occasionally you might want to query a transaction’s state in our system so you’ll be able to update it on your end. You can either use the TransferZero Transaction ID for this, or the External Id we set up earlier. In this example we’ll use the External ID

GET /v1/transactions?external_id=Transaction:GHS:91475

TransactionsApi api = new TransactionsApi(configuration);

TransactionListResponse response = api.GetTransactions(externalId: "Transaction:GHS:91475");

if (response.Object.Count > 0) {
  Transaction transaction = response.Object[0];
} else {
  // handle not found scenario
}

Dim api as TransactionsApi = New TransactionsApi(configuration)

Dim response as TransactionListResponse = api.GetTransactions(externalId:="Transaction:GHS:91475")

If response.Object.Count > 0 Then
    Dim transaction As Transaction = response.Object(0)
Else
    ' handle not found scenario
End If

TransactionsApi api = new TransactionsApi(apiClient);

TransactionListResponse response = api.getTransactions().externalId("Transaction:GHS:91475").execute();

if (response.getObject().size() > 0) {
  Transaction transaction = response.getObject().get(0);
} else {
  // handle not found scenario
}

const api = new TransferZeroSdk.TransactionsApi(apiClient);

const response = await api.getTransactions({external_id: "Transaction:GHS:91475"});

if (response.object.length > 0) {
  const transaction = response.object[0];
} else {
  // handle not found scenario
}

$api = new TransactionsApi();

$response = api->getTransactions([external_id => "Transaction:GHS:91475"]);

if (count(response->getObject()) > 0) {
  $transaction = response->getObject()[0];
} else {
  // handle not found scenario
}

api = TransferZero::TransactionsApi.new

response = api.get_transactions({external_id: "Transaction:GHS:91475"})

if !response.object.empty?
  transaction = response.object.first
else
  # handle not found scenario
end

Schedule the onboarding call

Once you have implemented all of the steps based on the example above you have fulfilled our requirements for a successful integration. Please schedule an onboarding call with us and we’ll check your implementation and allow access to our production environment if all is good.