Tracking Remittance Through Sweep to Third Party¶

Disclaimer: The following is provided for information purposes only. Bank makes no representation or warranty that use of a service in the manner described will exempt Client from any federal or state law, including those dealing with money services businesses, money transmission, banking or lending.

This document outlines a typical funds flow in a remittance program and explains how key GIB APIs, particularly Subtransactions and BOOK transfers, are used to support these flows.

Subtransactions represent the true parties to a remittance transfer, and thus their use helps to clearly delineate customer funds from operating funds while offering transparency to otherwise nested transactions. so that GIB can offer its customers the flexibility they need to route payment flows using the most efficient cost-effective means available.

We begin with a common funds flow, wherein a US-based consumer funds or has a third party fund a virtual account. When the consumer is ready to transfer the funds internationally, the fintech enables the FX conversion, and either first uses a BOOK transfer to move the funds to an operations account, then transfers the funds in bulk to a payout network, or simultaneously prefunds the payout provider and performs a BOOK transfer from virtual accounts to their operations account.

The scenario below provides an overview of one way a Fintech can use GIB's APIs to automate payment initiation and reporting at each step in this process.

Scenario: Barry is a gig worker on Giggly, a US-based gig working marketplace. Barry lives in Nigeria but is to be paid in USD by Giggly. Barry signs up for PayItForward, a fintech product offering services through Global Innovations Bank, who provides him with a virtual account that is nested within an FBO account. Barry provides Giggly with the virtual account information and Giggly initiates payments to the virtual account via ACH. Later, Barry uses Giggly to pay his electricity bill using NGN.

This guide assumes a Subclient and virtual account have already been created for the end-user. Follow this link for steps to create a Subclient and virtual account.

Prerequisites¶

The code snippets provided in this scenario require the following variables:

BASE_API_URL - The target GIB API domain, which can be found in the API-Reference.
ACH_API_URL - The target GIB API domain for ACH transactions, which can be found in the API-Reference.
API_KEY - The API key setup by the client for using the API. Can be generated using the Dashboard.
SUBCLIENT_ID - The ID for the target Subclient that the remittance is for. This guide assumes that this Subclient has a virtual account as part of a client FBO account.
OPERATIONS_ACCOUNT - The account number of the operations account the client has with GIB.
OPERATIONS_ACCOUNT_ID - The ID of the Subclient Account representing the operations account. See Steps 1 and 2 of this guide to create a Subclient Account for your core account.
COMPANY_ID - The ID for the client company, always your company's Tax ID/EIN preceded by a 1.

Step 1 - Onboarding: Create Subclient for Barry's Electricity Provider¶

Example: When PayItForward onboards Barry, they create a Subclient, and when Barry then initiates a payment to his electricity provider, PayItForward must ensure that a Subclient has been created for the beneficiary.

Before any tracking can happen, Subclient data for both the sender and the beneficiary must be created.

import requests

url = f"{BASE_API_URL}/subclient"

payload = {
  "name": "PowerByLagos",
  "external_key": "PIF-2025-001",
  "active": True,
  "type": "business",
  "data": {
    "type": "business",
    "legal_name": "PowerByLagos",
  },
  "address": {
    "country_alpha_2_code": "NG",
    "street_address_1": "123 Some Street",
    "city": "Lagos",
    "state_province": "Lagos",
    "postal_code": "100234",
  }
}

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("POST", url, json=payload, headers=headers)

response.raise_for_status()

TARGET_SUBCLIENT_ID = response.json()["id"]

Step 2 - Create Transaction and Subtransaction for the Sweep¶

Example: Barry uses PayItForward to convert his USD to Naira and use the converted currency to pay his bill for his electrical provider, PowerByLagos. PayItForward offers currency conversion and payout in Nigeria through either a 3^rd party payment service provider or an international affiliate. Once Barry initiates the transaction through PayItForward, the Naira is transferred to the beneficiary account via the 3^rd party. At this point the relevant USD funds in the FBO account at GIB are not considered customer funds, so PayItForward frequently sweeps all the funds into an operations account (also with GIB).

To transfer the money from the end-user's virtual account to the operations account, the client initiates a BOOK transfer.

To track the transfer from the end-user's account with the client to its final destination, a Subtransaction is created to record the event. This allows tracking the transaction as seen by the end-user, from the true sender (i.e., the onboarded client or end user) to the ultimate beneficiary. Setting the ultimate_beneficiary_subclient_id field signals the API to create the Subtransaction.

url = f"{BASE_API_URL}/transaction/from-subledger"

payload = {
    "type": "book",
    "origin_subclient_id": f"{SUBCLIENT_ID}",  # Barry's Subclient ID
    "destination_subclient_account_id": f"{OPERATIONS_ACCOUNT_ID}",  # The Subclient Account for PayItForward's Operations Account
    "ultimate_beneficiary_subclient_id": f"{TARGET_SUBCLIENT_ID}",  # The Subclient ID for PowerByLagos, Barry's Electricity Provider
    "external_key": "PIF-TX-007",  # Reference ID of transaction on client side
    "purpose": "Remittance",
    "reference": "INV-2025-Q1-003",  # Additional reference field
    "amount": 10000,
    "fees": 250,
    "test": False,
    "simulate": False,
}

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("POST", url, json=payload, headers=headers)

response.raise_for_status()

Step 3 - Create Transaction to Send to 3^rd Party¶

Example: Now that all the relevant funds are in their operations account, PayItForward transfers them to the 3^rd party..

To transfer the money from the operations account to the 3^rd party, the client initiates an outbound ACH transfer.

ach_data = {
  "fileHeader": {
    "fileCreationDate": datetime.today().strftime("%y%m%d"),
    "immediateOrigin": "091208154",  # GIB Routing Number
    "immediateOriginName": "Global Innovations Bank",
    "immediateDestination": "061000146",  # FRB Routing Number
    "immediateDestinationName": "Federal Reserve Bank",
  },
  "batches": [
 {
    "batchHeader": {
      "serviceClassCode": 200,
      "companyName": "PayItForward",
      "companyIdentification": f"{COMPANY_ID}",
      "standardEntryClassCode": "CCD",
      "companyEntryDescription": "PayItForward",
      "effectiveEntryDate": date.today().strftime("%y%m%d"),
      "ODFIIdentification": "091208154",  # GIB Routing Number
    },
    "entryDetails": [
      {
        "amount": 10000,  # USD Amount transferred, in cents
        "DFIAccountNumber": "123123123123",  # Destination account number
        "RDFIIdentification": "02100002",  # Destination routing number, without check digit
        "checkDigit": "1", # Check digit for destination routing number
        "transactionCode": 22,  # Credit to destination
        "individualName": "3rd Party Name",
      }
    ],
    "offset": {
      "routingNumber": "091208154",  # GIB Routing Number
      "accountNumber": f"{OPERATIONS_ACCOUNT}",
      "accountType": "checking",
      "description": "For offset",
    },
   }
 ]
}

url = f"{ACH_API_URL}/file/create"

payload = {
  "data": ach_data,
  "test": False,
}

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("POST", url, json=payload, headers=headers)

response.raise_for_status()

Resources¶

For more information on the endpoints used in this scenario see these API docs: