Forem: Kyle Pollock

TabaPay's first Postman Collection, check it out to test out different payments API use cases!

Kyle Pollock — Fri, 30 Jan 2026 15:59:47 +0000

Test Your Payments Use Case with Postman

Kyle Pollock for TabaPay ・ Jan 29

Test Your Payments Use Case with Postman

Kyle Pollock — Thu, 29 Jan 2026 22:52:32 +0000

You can use the Postman platform to test and build with the TabaPay API, alongside thousands of other APIs. Postman is used by more than 30 million users and more than half a million organizations, and now it’s easy to join them.

TabaPay now offers a Postman Collection, a bundle of API requests that will help you try out the TabaPay API for your use case. Explore your use cases to accept payments, payout funds, and test advanced payment features, all from a controlled Sandbox environment.

Our Postman Collection will help you:

Make your first successful API call
Understand required credentials and environment variables
Safely test real-world payment flows before production
Capture request and response fields used in the TabaPay API.

Why TabaPay API? Build for Scale, Security, and Reliability

TabaPay powers instant, real-time money movement for thousands of businesses across the U.S. and Canada—and is better than ever thanks to a newly revamped client portal.

The TabaPay API is engineered to operate at high scale while maintaining industry-leading security and availability.

TabaPay Highlights:

Up to 50% lower fraud rates compared to industry averages
2M+ transactions settled daily
$8B+ settled monthly
$230B+ total volume processed since inception
1.9B+ transactions processed
Number #6 U.S. Card-Not-Present (CNP) acquirer

Infrastructure & Availability:

99.99% system uptime
19 banking partners and growing, providing network redundancy

What’s Included in the Postman Collection

The TabaPay Postman Collection includes:

Pre-configured requests to test the Unified API
End-to-end flows for:
- Accepting payments (Pull)
- Payouts and disbursements (Push)
Support for multiple payment instruments:
- Cards
- Bank accounts
- RTP-enabled banks
- Apple Pay and Google Pay
Built-in scripting to automatically manage common Sandbox variables (optional)

Get Started

Before using the Postman Collection, you will need to begin your integration and compliance review with TabaPay. This includes receiving your Sandbox Credentials and whitelisting your IPs. To begin your implementation, email help@tabapay.com.

Step 1: Download the Collection

Download the TabaPay Postman Collection

Download Postman (if you don’t already have it installed)

Step 2: Configure Your Sandbox Environment

To begin testing, you’ll need to populate the following environment variables in your TabaPay Sandbox Environment. These values are provided by TabaPay when Sandbox credentials are issued.

You can customize the descriptions below or link to a credential reference page.

Required Environment Variables

Variable Name(s):

FQDN: The Sandbox base URL you are testing against
bearertoken: Authorization credential used to make authenticated API requests
ClientID: Your unique 22-character client identifier issued during onboarding

Note: These values are sensitive credentials. Never expose them publicly or share them with anyone who is not authorized.

Step 3: Make Your First API Call

Once the environment variables are populated:

Navigate to Retrieve Client
Select Send

A successful response confirms:

Your credentials are valid
Your client configurations and limits

Your environment is configured correctly, and you’re ready to begin testing additional workflows

Tokenization

Tokenization is the process of replacing sensitive payment data (e.g. a card number or bank account number) with a unique, non-sensitive placeholder called a token. TabaPay enables its users to generate tokens in many different use cases, but one of the main uses is payment tokenization with Account IDs—rendered as the variable accountID. An accountID is TabaPay's own unique set of 22-character string generated by Create Account that represents a single payment card number or bank account.

Managing accountIDs in Sandbox

Due to PCI standards, tokenized payment credentials are widely used among fintech platforms. Tabapay's accountIDs are commonly used among clients for all use cases for both payment acceptance and payouts.

Using the TabaPay Postman Collection, you can generate these accounts in Sandbox.

To Generate an AccountID:

Go to the TabaPay API Postman Collection
Go to Account > Create Account
Choose the request based on your payment instrument:
1. Card
2. Bank
3. RTP-enabled bank
Select Send

When the request succeeds:

A new accountID is generated
The Sandbox Environment variable is automatically updated under Current Value
Once configured, you can freely test different payment flows using your generated accountID.

Optional: Disable Auto-Updates

If you are testing different use cases, and generating multiple accountIDs you may want to avoid automatically updating the accountID environment variable. If you prefer a more manual control to avoid the accountID variable automatically updating, complete the following:

Go to Collections > *TabaPay API *
Select Account > POST Create Account
Go to Scripts
Paste in the following, comment out, or delete the script in Post-res (Post response).

JavaScript
//var jsonData = pm.response.json();
//if (jsonData.accountID){
// pm.environment.set("accountID", jsonData.accountID); 
//}

Your accountIDs variable should now remain unchanged after creating new accountIDs.

Note: The script will be active by default you will need to comment out to disable.

Working with transactionIDs

The same process or updating will happen for the following unique IDs

transactionIDs: Generated when transactions are created. The transactionID variable is automatically updated in your Sandbox Environment by default.

If you do not want this behavior:

Navigate to the relevant Post Create Transaction - Pull Card, or, Post Create Transaction - Push Bank

Go to the Scripts section > Post-res and follow the same steps as in Optional: Disable Auto-Updates.

Other Auto-Updates include

KeyID: To remove go to Collections > Key > POST Create Key > Scripts > Post-res.

Types of Transaction Flows

Other transaction flows include:

Create Transaction – Pull Card
Create Transaction – Pull Bank
Create Transaction – Push to Card
Create Transaction – Push Bank

What’s Next?

At this point, you can:

Explore additional payment features
Modify request bodies to simulate real-world scenarios
Validate end-to-end payment flows in Sandbox

To move forward with your integration and request Sandbox access:

📧 Email: help@tabapay.com, and please include:

Your company name and website
Intended use case
A request for Sandbox credentials, and IP whitelisting

Our team will help you get up and running.

How to Read a Payment Response

Kyle Pollock — Mon, 16 Oct 2023 18:37:37 +0000

The total value of transactions of digital payments is projected to reach €8.89 trillion EUR in 2023, or equal to $9.46 trillion USD. The ability to seamlessly process payments is a cornerstone of success for businesses worldwide. Behind every click to purchase lies a complex web of data and transactions, orchestrated by Payment APIs. These APIs facilitate the exchange of money between buyers and sellers, providing a vital link in the digital economy.

We'll delve into how to read and understand an API Payment response. We'll explore the core components of such responses, including common fields and their meanings.We'll also draw comparisons and highlight the nuances in payment response structures.

The whole purpose of a payment API is to move funds from one location or group to another. Transactions can not only happen from a customer to a business, but also from a business to a business, and even a customer to a customer. Today we will mainly focus on the B2C aspect of a transaction.

The Payment Object is probably the most important object in the response, usually containing fields like amount, currency, country, payment type, and an ID for the customer. We’ll look at these aspects and several other elements of a payment API.

Reading a Payment API Response

Reading a payment response is vital as it verifies a successful, or unsuccessful transaction, ensures the accuracy of debited or credited amounts, and serves as evidence for reconciliation, dispute resolution, and compliance needs. Payment responses also provide valuable data for reporting and analytics, aiding businesses in making informed decisions and improving the customer experience by assuring clients of correct payment processing.

Key Payment Fields

Payment APIs often share common fields like amount, payment_method, country, or currency. Fields that are required for an API may vary depending on the purpose of the request, regulatory standards, security needs, and technology used. For example, APIs for cross-border transfers may include multiple currencies and fees, while peer to peer transfers may emphasize recipient data. These variations are necessary to cater to diverse financial services, differing regional regulations, and security considerations. Each fintech strives to create tailored experiences and solutions while ensuring compliance with legal regulations. Developers also play a role, with API structure, design and different integration requirements. It's essential to have knowledge of basic payment API fields and concepts to adhere to specific use cases.

Amount: Measuring the Transaction

The amount field in Payment API responses is the monetary value involved in a transaction. It's essential for both buyers and sellers to verify the correct amount is being processed, especially in the context of refunds or partial payments.

{
"amount": 100
}

Sometimes in countries with 3DS, there will be two amount fields, until the card is verified.

"amount": 0,
"original_amount": 100,

Once the card is verified, both the amount and original_amount will show the total. Refer to the Status section about more payment status information.

"amount": 100,
"original_amount": 100,

Currency Code: The Language of Payments

Currency codes define the monetary unit used for a transaction. Accurate currency information ensures that payments are processed correctly and avoids potential currency exchange discrepancies. Currency codes are often in the ISO 3-Letter Currency Code format. This is set by the ISO (International Organization for Standardization). Examples include GBP (British Pounds), EUR (Euros), USD (US Dollars), or SGD (Singapore Dollars).

"currency_code": "GBP",

Country Code: Identifying the Payment Origin

The country code represents the country of origin for a Payment API transaction, typically using the ISO 3166-1 alpha-2 format, which consists of two letters. Accurate country information is essential to ensure that transactions comply with local regulations and to facilitate international payment processing.

For example, the two-letter ISO country code for the United States is "US," for the United Kingdom, it is "GB," and for Germany, it is "GE."

Here's an example of how a country code can be used in the context of a Payment API:

"country_code": "GB"

The country code helps identify the origin of the transaction, which can be vital for compliance, tax, and legal purposes in international payment processing.

Payment Method: What is Used to Pay

Knowing the payment method used is crucial for businesses to manage various payment channels effectively. It can also affect transaction fees and the customer's experience as they prefer certain payment methods over others.

This tells us the specific type of payment that was made within each category: credit card, bank transfer, cash, or e-wallet. For example, Rapyd's payment_method field tells us that the payment was made using a Visa card based in the United Kingdom (GB).

"type": "gb_visa_card",

Customer ID: Identifying the Payer

Customer identification is crucial for businesses to maintain a record of their customers and provide tailored services. It's also essential for dispute resolution and customer relationship management. This is a unique identifier for the customer making the payment starting with cus_1234098091234.

        "customer_token": "cus_183225bd57e4bc4967bf8b4ddc9c6144"

Status: Tracking the Payment's Journey

The status of a payment reveals its current state. Whether it's active, closed, or encountering an error, understanding payment status is vital for monitoring and managing transactions. This indicates the current state of the payment, whether it's active, closed, or has encountered an error. For example, Rapyd's status for active payments is ACT. But the status changes to CLO for closed and completed transactions, and ERR for payment errors.

"status": "ACT",

Additional Payment Information

Not all transaction data will be a part of a basic payment, for example a customer purchasing an item in the same country and currency as the business. However, in global transactions, there are more factors that can become required data in specific use cases like cross-border purchases, used hosted payment pages, or even bank transfers.

Payment URLs: Navigating the Payment Journey

Payment URLs are essential for redirecting customers to the appropriate pages based on payment outcomes. A well-defined redirection mechanism ensures a seamless customer experience. URLs providing redirection points for customers based on payment outcomes, including success or failure. Rapyd offers redirect_url for success and error_payment_url for failure. These are useful for when using hosted pages, and also for payment methods with third party verification services like 3DS card verification, or evem bank redirect payments.

"redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_a132ede4aa30e0b53f15e53c8b69e189",
"complete_payment_url": "https://rapyd.net",
"error_payment_url": "https://docs.rapyd.net",

Exchange Rate (FX Rate): Handling Foreign Exchange

In international transactions, the exchange rate plays a pivotal role. It directly impacts the final amount received by the seller and ensures accurate financial accounting, which is relevant in foreign exchange transactions. This rate determines the conversion between different currencies. The field requested_currency or merchant_requested_currency, contains one of the currencies in the transaction.

See the example below to show that the SGD (Singapore Dollar) is charged to the customer and GBP (British Pounds) is received by the merchant.

"currency_code": "SGD",
"country_code": "SG",
"merchant_requested_currency": "GBP",

Payment Fees: Assessing Transaction Costs

Payment fees can significantly affect the financial outcome of a transaction. Understanding these fees helps businesses manage their profitability and pricing strategies. This would include any additional fees associated with the payment beyond the transaction amount.

We see the payment fees object, which contains different fees including transaction fees, fx fees and gross fees. You can learn more about FX fees at https://docs.rapyd.net/en/create-payment.html.

"fx_rate": 1,
"payment_fees": {
"transaction_fee": {
"calc_type": "gross",
"value": 2,
"fee_type": "absolute"
},
"fx_fee": {
"calc_type": "gross",
"value": 2.5
},
"gross_fees": 27,
"net_fees": 0,
"total_merchant_fees": 1.16

Next Action: Guiding Customers Forward

Next action details are critical for customers to follow the necessary steps to complete a payment, especially in cases requiring additional authentication or confirmation. next_action Describes what the customer needs to do next as the customer would need to validate their card, or log into their bank account for a bank redirect.

"next_action": "3d_verification",

Instructions: Clearing the Path for Customers

Providing clear instructions to customers is essential for complex transactions. It reduces user friction and ensures payments are completed accurately. Instructions are necessary for directions to the customer who would pay by bank transfer, or cash and follow through on sending funds. For example the bank transfer to log into their bank and send funds to the correct account. When a customer pays cash through a payment API like Rapyd, then they receive a QR code on their mobile phone, and give cash to a local corner store cashier after scanning the QR code.

"instructions": [
{
"name": "instructions",
"steps": [
{
"step1": "Please Transfer funds to the provided DBS bank account using your Singapore based bank account via FAST (preferred), MEPS or GIRO."
}
]
}
],

Visual and Textual Codes: User-Friendly Guidance

Visual and textual codes can simplify complex actions for customers. They help convey information efficiently and enhance the user experience. Visual and text codes may be provided to assist customers in completing payment-related actions.

"visual_codes": {},
"textual_codes": {
"DBS Account No": "4833464377151602"
},

Payment Category: Categorizing Payment Methods

Understanding the type and category of payment methods used can help businesses tailor their offerings and improve customer satisfaction. Payment categories distinguish the type of payment method used (e.g. card, bank transfer) and its broader group type.

"payment_method_type_category": "bank_transfer",

Payment Timestamps: Tracking Time

Time-related information, such as payment creation and last capture timestamps, is crucial for financial record-keeping, auditing, and dispute resolution. Often a unix timestamp, indicating a specific moment in time in seconds since January 1, 1970, will be used with a payment API. For example a unix timestamp could look like 1634034238.

"expiration": 1698292230,

Custom Fields

Custom Fields: Payment APIs can allow for custom fields in the response. This can be highly beneficial for businesses looking to include specific information or metadata about the payment.

"payment_method_options": {},
"metadata": {
"merchant_defined": true
},

Tax Collection Fees

Tax ID Collection: Some fintech APIs support tax ID collection, which is crucial for businesses dealing with taxation and compliance issues. This field is significant for financial record-keeping.

Automatic Tax: Some payment API responses may include information about automatic tax calculation, which simplifies the tax compliance process for businesses operating in different regions.

Rapyd has fees you can charge for tax collection.

  "object": "tax.settings",
  "defaults": {
    "tax_behavior": null,
    "tax_code": "txcd_10000000"

Coupon Codes

Promotion Codes: Some payment APIs may provide the option to allow or disallow promotion codes in the payment process. This can be essential for managing promotional campaigns and discounts.

Coupons can be used for both for single payments and for subscriptions. Coupons may not always show up in the response, but they would appear in the request and a discount field would show that a coupon was used.

{
        "billing": "pay_automatically",
        "created_at": 1592379647,
 "coupon": “15OFF”,       
 "discount": 15,
 }

Put Knowledge into Action

To further understand payment API responses you can explore Rapyd docs and read through more of the examples in this article. To experiment with Payment API responses, consider using Postman, a versatile platform for API testing. Rapyd offers OpenAPI documentation and examples, allowing you to interact with our APIs and observe responses firsthand. You can explore Rapyd's API responses by visiting https://www.postman.com/rapyd-dev.

You can take a look directly at the API definition and responses at Rapyd Dev Postman API

Navigating Payment API responses is integral to e-commerce success. As businesses increasingly rely on digital transactions, mastering the nuances of these responses is a valuable skill. Whether you're using Rapyd, or any other provider, a deep understanding of payment response structures is your ticket to ensuring smooth and secure online transactions.

Rapyd's Documentation Refresh

Kyle Pollock — Mon, 18 Sep 2023 21:29:25 +0000

Great products are built with innovative, and hard working developers. Great partnerships, and platforms are built with simple, clear, and comprehensive documentation. For developers, businesses, and anyone looking to build your next payments solution, consider Rapyd’s fintech-as-a-service platform. Rapyd believes in investing in documentation and infrastructure to speed up each page, and improve the user experience for developers looking to build their fintech solution. Rapyd’s newly refreshed documentation is a resource that empowers you to understand and build on the Rapyd API.

One-Stop Knowledge Hub

The first thing you'll notice about the revamped Rapyd documentation is that everything you need is now in one place. Whether you're a developer seeking to integrate Rapyd's services into your application or a business looking to leverage Rapyd's financial capabilities, you'll find everything you need organized in a single, user-friendly platform.

Get Started: Your Launchpad

Are you new to Rapyd's ecosystem? The Get Started section serves as your launchpad. Here, you can start your journey with step-by-step guides that walk you through making your first API call in your preferred languages—Python, Javascript, PHP, Ruby, .NET, and more. It's the perfect starting point for those taking their initial steps into the world of Rapyd.

Product Guide: Your Comprehensive Handbook

The Product Guide is your comprehensive handbook, offering insights into the diverse range of products and services Rapyd provides. Whether it's payments, payouts, wallets, or issuing for your financial service, this section provides you with a clear understanding of what Rapyd has to offer, helping you choose the right solutions for your specific needs.

Client Portal Guide: Navigating with Ease

For those who have not yet signed up for an account you can do so on the Client Portal sign up page. As you build in the Rapyd ecosystem, the Client Portal Guide is your navigation companion for your dashboard. The Client Portal documentation guide helps you know where to go to be able to efficiently manage your payments and payouts within a user-friendly, no-code environment. From activation to full utilization, this guide ensures you get the most out of the Client Portal.

Developer Guide: Crafting with Precision

The Developer Guide is a resource for crafting seamless integrations with Rapyd's services, information on payment statuses, and error handling. Find insights, best practices, and security considerations to ensure your integration process is not only smooth but also secure.

API Reference: Sleek and Speedy

One of the standout features of the new documentation is the revamped API Reference section. The design is sleek and minimalistic, prioritizing ease of use and quick access to vital information. Finding what you need within the API reference has never been faster or more straightforward. It's your ultimate toolbox for building fintech solutions.

Plugins: Expanding Possibilities

For those seeking to expand the capabilities of their applications, the Plugins section is a treasure trove of possibilities. Explore a range of plugins designed to enhance your offerings and meet your specific business needs.

Point-of-Sale: Where Commerce Meets Convenience

In the world of retail and commerce, the Point-of-Sale section is your guide to seamless transactions. Whether you're a business owner or developer for in-person payments, you'll find valuable insights into integrating Rapyd's services into your point-of-sale systems.

Glossary: Decoding Fintech Jargon

Fintech is rife with jargon and acronyms. The Glossary section is your decoder ring, helping you navigate the sometimes complex terminology of the financial world. It's an essential resource for anyone seeking to demystify fintech.

Improving Docs for the Developer

The new Rapyd documentation isn't just a redesign. Its speed and performance have undergone significant improvements. Accessing information, particularly in the API reference section, is now lightning-fast. The sleek and minimalistic design ensures that API references are easy to read and understand, even for those new to the fintech world.

Rapyd has integrated hundreds of services and partners all into one API, and offering developers access to clear, fast, and comprehensive documentation can make all the difference. Rapyd's documentation refresh brings all the essential information and resources you need into one place. Whether you're just getting started or you're a seasoned developer or business owner, this revamped knowledge hub is your passport to success in the world of financial services. Dive in, explore, and unlock the full potential of Rapyd's Fintech-as-a-Service platform. Your journey starts here. Check out docs.rapyd.net and start building now.

Empowering Rapyd Payments with OpenAPI

Kyle Pollock — Mon, 18 Sep 2023 19:19:56 +0000

OpenAPI, formerly known as Swagger, is a specification for designing, documenting, and consuming RESTful APIs (Application Programming Interfaces). OpenAPI provides a standardized way to describe the structure, operations, and functionality of an API. OpenAPI allows developers to generate documentation, create client SDKs (Software Development Kits), and automate API-related tasks.

Why OpenAPI Matters for Rapyd

What is it that makes OpenAPI a valuable tool for developers? Here are some reasons why we would use OpenAPI at Rapyd.

API Documentation: OpenAPI allows us to generate interactive and user-friendly documentation for our API. It provides a machine-readable format that can be easily consumed by developers, making it easier for them to understand how to use our API effectively.

Design-First Approach: OpenAPI promotes a design-first approach to building APIs. By defining the API specification upfront, we can ensure consistency and clarity in the API's structure and behavior. This helps both the Product managers and Engineers to build the API, and the developer community to have a clear understanding of the API contract. You can think of an API contract as a recipe that tells two pieces of software how to talk to each other. Just as a cookbook that gives specific instructions on ingredients, and cooking steps the API contract will set rules on defining endpoints, data formats, and behavior to ensure seamless integration and interoperability.

Code Generation: OpenAPI specifications can be used to automatically generate client SDKs, server stubs, and other code artifacts. This saves time and effort by eliminating the need to write boilerplate code for API integration. Generated SDKs can provide a convenient way for developers to interact with our API using their preferred programming language.

Testing and Validation: OpenAPI specifications can be used to validate API requests and responses. We perform automated testing against the specification to ensure the API implementation adheres to the defined contract. This helps identify potential issues and inconsistencies early in the development process.

API Governance and Collaboration: OpenAPI provides a common language and format for describing APIs, making it easier for teams to collaborate on API design and development. It allows for better communication between API providers and consumers, enabling teams to work together effectively.

Empowering API Developers

Once we publish an OpenAPI specification, consumers can use it to understand and interact with our API.

Here's how consumers can leverage the OpenAPI specification:

Manual Integration: Developers can manually integrate with our API by referring to the OpenAPI specification. They can use the specification to understand the structure of the API's endpoints, the expected request payloads, and the format of the responses. By following the API contract defined in the OpenAPI specification, consumers can manually write code to make HTTP requests and handle the API responses in their preferred programming language.

Code Generation: OpenAPI allows for automatic code generation, which simplifies API integration for consumers. The OpenAPI specification can be used with code generation tools, such as Swagger Codegen or OpenAPI Generator, to generate client SDKs or libraries in various programming languages. These generated SDKs provide pre-built functions and classes that abstract away the low-level details of making API requests and handling responses. Consumers can then import these SDKs into their projects and use the provided methods and classes to interact with our API more easily.

API Explorers: Many API development platforms and tools provide built-in API explorers that can consume the OpenAPI specification and provide an interactive interface for testing and exploring the API. These explorers allow consumers to make API requests, view responses, and experiment with different parameters. Swagger UI and ReDoc are popular examples of API explorers that can consume OpenAPI specifications.

API Gateway Configuration: API management servers typically include an API gateway component that handles the routing and forwarding of API requests. By importing the OpenAPI specification into the API management server, the gateway can automatically configure the necessary routing rules based on the defined endpoints and paths in the specification. This simplifies the setup process and ensures that incoming requests are properly routed to the corresponding backend services.

Examples for use OpenAPI in API Management Gateways:
https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html
https://learn.microsoft.com/en-us/azure/api-management/import-api-from-oas?tabs=portal

Getting started with Rapyd OpenAPI on Postman

Go to https://postman.com/rapyd-dev and goto Collections > Select Fork.
Go to Environments, select the three dots next to RapydSB openAPI > Select Fork.

As you fork both the Collection and Environment, you can import them into your own designated environment.

Sign-up to Rapyd Client Portal,
Grab your API credentials to copy the access and secret keys from the Developers tab.
Paste the access and secret key into the Postman Environment.
Test your collection by calling GET https://sandboxapi.rapyd.net/v1/data/countries.

Note: The endpoint in Postman should look like {{baseUrl}}/v1/data/countries.

Copy the OpenAPI into Swagger

Go to the API section in Rapyd OpenAPI in Postman.
Select the down arrow on Rapyd-api
Select the down arrow on Definition.
Select Rapyd-api-Beta.yaml or Rapyd-api.yaml.
On the right panel, select the copy icon in between the wrap text and search icon.

Go to the Swagger Editor and paste the OpenAPI in the content section.

Now you can look at generating samples and working on the Rapyd API right within Swagger.

For any questions you can open up a topic in the Rapyd Developer Community.

How to Set Up a Swift Payout with Rapyd Disburse API

Kyle Pollock — Tue, 12 Sep 2023 19:54:40 +0000

Swift—the Society for Worldwide Interbank Financial Telecommunications—is a widely popular network used for international money transfers between financial institutions, mainly banks, allowing businesses to easily pay their customers and employees in different countries. Swift’s wire transfer method is the preferred payment method of many businesses worldwide due to its broad availability, cost-effectiveness, security, and reliability.

By pairing Swift with the Rapyd Disburse API, your business can make fast and cost-effective international transactions, ensuring that your customers, business partners, and employees receive their payments in their local currency, on time. Rapyd Disburse is one of Rapyd’s many tools that allow businesses to issue international payments.

By the end of this tutorial, you will be able to use Rapyd’s sandbox environment to get API keys, perform and authorize API requests, create a Node.js app that uses the Rapyd Disburse API to easily send Swift payments to your customers and employees, and use Rapyd webhooks to listen to and confirm payout transactions upon completion.

Implementing Swift Payments

In the following sections, you will learn how to use the Rapyd Disburse API to issue international Swift payments by completing the following actions:

Getting API Keys
Setting up your application and the Node.js server
Setting environment variables
Creating a utilities helper
Creating routes
Creating a server instance
Creating a payment interface page
Creating event handlers
Creating the controller
Running and testing the application
Creating a webhook to receive payment confirmation

In order to follow this tutorial and send Swift payouts using the Rapyd Disburse API, you’ll need a Rapyd account. If you haven’t created one yet, you can sign up here.

You can find the full code for this project in this GitHub repository.

Getting the API Keys

Log in to your Rapyd account and activate the sandbox button at the top right corner of your account dashboard. Then, click the Developer menu item in the left side menu to get your sandbox credentials. You can use these credentials during the development and testing phases.

Setting Up Your Application

In this tutorial, you will be using Express to create a Node.js server. As a starting point, create a new directory, navigate to it in your terminal window, and run the following command to create a package.json file, which will store the dependencies for your project:

npm init -y

Then run the following command to install Express and the other dependencies needed for the project:

npm install express dotenv body-parser ejs

You'll also be using nodemon to make the development process easier. Run the following command to install it:

npm install -g nodemon

To keep your code organized with regard to the structure of this application, create these five directories inside your project’s main directory (e.g. mkdir controllers, etc.):

controllers
helpers
public
routes
views

Setting Environment Variables

This file holds the environment variables that your application will use to authorize API requests. The three variables that you will use for this project are API key, secret key, and wallet ID.

Create the .env file in the main directory and paste in the following code:

NODE_ENV=development

ACCESS_KEY=YOUR_ACCESS_KEY
SECRET_KEY=YOUR_SECRET_KEY
PAYOUT_WALLET_ID=YOUR_WALLET_ID_HERE

Add your API and secret keys, found on the developers page as the first two variables and leave the wallet ID empty for now. You will get this value later in this tutorial.

Creating a Utilities Helper

In the /helpers directory, create the utilities.js file and paste in the following code:

/*
* Environment Variables
*/
const https = require('https');
const crypto = require('crypto');
const dotEnv = require('dotenv');
const log = false;

dotEnv.config();

const secretKey = process.env.SECRET_KEY; // Your API Access key
const accessKey = process.env.ACCESS_KEY; // You API secret key

/*
* Make a Request to Rapyd API
*/
async function makeRequest(method, urlPath, body = null) {
  try {
    // API Request parameters
    httpMethod = method;
    httpBaseURL = "sandboxapi.rapyd.net";
    httpURLPath = urlPath; // The request path
    salt = generateRandomString(8); // Randomly created for each request
    idempotency = new Date().getTime().toString(); // Used for payment creation requests
    timestamp = Math.round(new Date().getTime() / 1000); 
    signature = generateSignature(httpMethod, httpURLPath, salt, timestamp, body) // Request Signature
    const options = {
      hostname: httpBaseURL,
      port: 443,
      path: httpURLPath,
      method: httpMethod,
      headers: {
        'Content-Type': 'application/json',
        salt: salt,
        timestamp: timestamp,
        signature: signature,
        access_key: accessKey,
        idempotency: idempotency
      }
    }

    return await httpRequest(options, body, log);
  }
  catch (error) {
    console.error("Error generating request options");
    throw error;
  }
}

/*
* Generate Request Signature
*/
function generateSignature(method, urlPath, salt, timestamp, body) {

  try {
    let bodyString = "";
    if (body) {
      bodyString = JSON.stringify(body);
      bodyString = bodyString == "{}" ? "" : bodyString;
    }

    let toSign = method.toLowerCase() + urlPath + salt + timestamp + accessKey + secretKey + bodyString;
    log && console.log(`toSign: ${toSign}`);

    let hash = crypto.createHmac('sha256', secretKey);
    hash.update(toSign);
    const signature = Buffer.from(hash.digest("hex")).toString("base64")
    log && console.log(`signature: ${signature}`);

    return signature;
  }
  catch (error) {
    console.error("Error generating signature");
    throw error;
  }
}

/*
* Generate a Random Salt String
*/
function generateRandomString(size) {
  try {
    return crypto.randomBytes(size).toString('hex');
  }
  catch (error) {
    console.error("Error generating salt");
    throw error;
  }
}

/*
* Create an HTTP Request
*/
async function httpRequest(options, body) {

  return new Promise((resolve, reject) => {

    try {

      let bodyString = "";
      if (body) {
        bodyString = JSON.stringify(body);
        bodyString = bodyString == "{}" ? "" : bodyString;
      }

      log && console.log(`httpRequest options: ${JSON.stringify(options)}`);
      const req = https.request(options, (res) => {
        let response = {
          statusCode: res.statusCode,
          headers: res.headers,
          body: ''
        };

        res.on('data', (data) => {
          response.body += data;
        });

        res.on('end', () => {

          response.body = response.body ? JSON.parse(response.body) : {}
          log && console.log(`httpRequest response: ${JSON.stringify(response)}`);

          if (response.statusCode !== 200) {
            return reject(response);
          }

          return resolve(response);
        });
      })

      req.on('error', (error) => {
        return reject(error);
      })

      req.write(bodyString)
      req.end();
    }
    catch(err) {
      return reject(err);
    }
  })

}


exports.makeRequest = makeRequest;

The functions in this file handle authorizing and sending requests to the Rapyd API servers. You will use these functions later to perform API calls. The utilities.js file includes the following four functions:

makeRequest: Includes the logic to communicate with the Rapyd sandbox server
generateSignature: Generates a Rapyd API request signature
generateRandomString: Generates a salt string for the HTTP request
httpRequest: Creates an HTTP request and returns the response

Creating Routes

Create a file named index.js in the /routes directory and paste in the following code:

const express = require('express');
const path = require('path');
const router = express.Router();
const bodyParser = require('body-parser');
const payoutController = require('../controllers/payoutController')

const app = express();

// Set Render Engine
app.use('/public', express.static('public'));
app.set('view engine', 'ejs');

// Load Body parser for JSON responses
router.use(bodyParser.urlencoded({extended: true}));
router.use(bodyParser.json());

// GET: Home Route
router.get('/', async (req, res) => {
    res.render('../views/payCustomer');
});

// POST: Required Fields
router.post('/get-required-fields', async (req, res, next) => {
    payoutController.getRequiredFields(req, res, next);
});

// POST: Send payout
router.post('/send-payment', async (req, res, next) => {
    payoutController.sendPayment(req, res, next);
});

// POST: Payment Completed Webhook URL
router.post("/payment-complete", (req, res) => {
  console.log(req.body);
  res.status(200).end(); 
});

module.exports = router;

In this /routes/index.js file, the ejs module is set as the rendering engine to render HTML and the BodyParser module is configured to handle JSON responses.

Then, the file includes 4 routes:

GET /: The homepage
GET /get-required-fields: The endpoint to get the required fields for the Swift payment method
POST /send-payment: The endpoint to send a Swift payment
POST /payment-complete: The webhook URL to handle the payment complete action

Creating a Server Instance

Create an index.js file in the main project directory and paste in this code:

const express = require('express');
const path = require('path');
const router = require('./routes/index');


const app = express();

app.use('/public', express.static('public'));
app.set('view engine', 'ejs');

app.use('/', router);
app.listen(3000);

This is the file where you create the server instance. The imported modules are path, to set the public resources folder, and router, so the server can use the routes that you have previously set in the /routes/index.js file.

Creating a Payment Interface Page

Now, create an payCustomer.ejs file in the /views folder. Notice that the file extension is .ejs because you are using the ejs module as the rendering engine. Then, paste this HTML code to this file:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>SWIFT Payout using Rapyd Disburse</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
  <link rel="stylesheet" href="public/app.css">
</head>
<body>
  <div class="row">
    <div class="col-md-3">
    </div>
    <div class="col-md-6 bg-light">
      <form id="checkoutForm">
        <h1> Rapyd Disburse Swift Payment</h1>

        <!-- Initial form fields to get the required fields for the Swift payment method by country -->
        <fieldset>

          <p>
            <label for="payout_currency" class="form-label">Customer's Currency</label>
            <input type="text" required id="payout_currency" name="payout_currency" class="form-control" placeholder="Payout Currency" required>
          </p>

          <p>
            <label for="user_country">Country</label>
            <input type="text" required id="user_country" name="user_country" class="form-control" placeholder="Country Code, ex: FR" required>
          </p>

          <p>
            <label for="transaction_amount">Amount</label>
            <input type="text" required id="transaction_amount" name="transaction_amount" class="form-control" placeholder="Amount" required>
          </p>

        </fieldset>

        <!-- The Button to execute the "getRequiredFields" request -->
        <p>
          <button type="button" id="pay-button" class="btn btn-primary form-control">Pay Salary</button>
        </p>

        <fieldset id="payment-required-fields">
          <!-- Payment fields will show up here -->
        </fieldset>

        <!-- Send Payment Button -->
        <p>
          <button type="submit" id="send-payment-button" class="btn form-control btn-success">Send Payment</button>
        </p>

        <!-- Loading Notification -->
        <div class="alert alert-success request-status-bar" id="request-status-success" role="alert">
          Payment Sent
        </div>
        <!-- Success Notification -->
        <div class="alert alert-warning request-status-bar" id="request-status-loading" role="alert">
          Processing...
        </div>
        <!-- Error Notification -->
        <div class="alert alert-danger request-status-bar" id="request-status-error" role="alert">

        </div>

      </form>
    </div>
    <div class="col-md-3">
    </div>
  </div>

</body>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<script src="public/app.js"></script>
</html>

The HTML code includes the following:

The fields needed to get the Swift payment’s required fields, which are payout currency, country code, and transaction amount.
A button to get the required fields and a hidden button to send the payment.
Three notification <div> tags: one for payment success, one for loading, and one for errors.
Four imported resources: Bootstrap CSS for styling and jQuery for JavaScript, as well as app.css and app.js files.

To add some style to the interface page, create a file named app.css in the public directory and paste this CSS code:

label {
    text-transform: capitalize;
}

#send-payment-button{
    display: none;
}

.request-status-bar {
    text-align: center;
    display: none;
}

Creating Event Handlers

To handle the form submissions using AJAX, create the app.js file in your /public directory and paste this code:


$(function(){ 

// Pay Salary button Event Listener
  $("#pay-button").click(function(event){
    event.preventDefault();
    $("#request-status-loading").slideDown();

  // AJAX Call
    $.ajax({
      type: 'POST',
      url: '/get-required-fields',
      data: {
        'sender_currency': 'USD',
        'sender_country': 'US',
        'beneficiary_country': $("#user_country").val(),
        'payout_currency': $("#payout_currency").val(),
        'sender_entity_type': 'company',
        'beneficiary_entity_type': 'individual',
        'payout_amount': $("#transaction_amount").val()
      }, 
      success: function (data, status, xhr) {

        //Create Beneficiary Fields
        $("#payment-required-fields").append("<h2>Beneficiary Information</h2>");
        $.each(data.beneficiary_required_fields, function(propName, propVal) {
          var fieldName = propVal.name;
          var isRequired = propVal.is_required == true? "required" : "" ;
          var fieldDesc = propVal.description? propVal.description : "";
          $("#payment-required-fields").append("<label for='"+fieldName+"' class='form-label'>"+fieldName.replace("_", " ")+"</label>");
          if(propVal.is_required == true) $("#payment-required-fields").append("*");
          $("#payment-required-fields").append("<input type='text' id='beneficiary_"+fieldName+"' name='beneficiary_"+fieldName+"' class='form-control' placeholder='"+fieldDesc+"' "+isRequired+">");
        });

        //Create Sender Fields
        $("#payment-required-fields").append("<h2>Sender Information</h2>");
        $.each(data.sender_required_fields, function(propName, propVal) {
          var fieldName = propVal.name;
          var isRequired = propVal.is_required == true? "required" : "" ;
          var fieldDesc = propVal.description? propVal.description : "";
          $("#payment-required-fields").append("<label for='"+fieldName+"' class='form-label'>"+fieldName.replace("_", " ")+"</label>");
          if(propVal.is_required == true) $("#payment-required-fields").append("*");
          $("#payment-required-fields").append("<input type='text' id='sender_"+fieldName+"' name='sender_"+fieldName+"' class='form-control' placeholder='"+fieldDesc+"' "+isRequired+">");
        });

        //Create Transaction Fields
        $("#payment-required-fields").append("<h2>Transaction Details</h2>");
        $.each(data.payout_options, function(propName, propVal) {
          var fieldName = propVal.name;
          var isRequired = propVal.is_required == true? "required" : "" ;
          var fieldDesc = propVal.description? propVal.description : "";
          $("#payment-required-fields").append("<label for='"+fieldName+"' class='form-label'>"+fieldName.replace("_", " ")+"</label>");
          if(propVal.is_required == true) $("#payment-required-fields").append("*");
          $("#payment-required-fields").append("<input type='text' id='transaction_"+fieldName+"' name='transaction_"+fieldName+"' class='form-control' placeholder='"+fieldDesc+"' "+isRequired+">");
        });


        // Show Status
        $("#request-status-error").slideUp();
        $("#request-status-loading").slideUp();
        $("#pay-button").slideUp();
        $("#send-payment-button").slideDown();
      },
      error: function (jqXhr, textStatus, errorMessage) {
        // Show Error
        $("#request-status-loading").slideUp();
        $("#request-status-error").slideDown();
        $("#request-status-error").html(errorMessage);
        console.log('Error' + errorMessage);
      }
    });

  });


// Send button Event Listener
  $("#send-payment-button").click(function(event){
    event.preventDefault();

    $("#request-status-error").slideUp();
    $("#request-status-loading").slideDown();

    // AJAX Call
    $.ajax({
      type: 'POST',
      url: '/send-payment',
      data: {
        'payout_currency': $("#payout_currency").val(),
        'sender_country': 'US',
        'sender_address': $("#sender_address").val(),
        'beneficiary_country': $("#beneficiary_country").val(),
        'sender_entity_type': 'company',
        'beneficiary_address': $("#beneficiary_address").val(),
        'payout_amount': $("#transaction_amount").val(),
        'beneficiary_address': $("#beneficiary_address").val(),
        'beneficiary_city': $("#beneficiary_city").val(),
        'beneficiary_country': $("#beneficiary_country").val(),
        'beneficiary_first_name': $("#beneficiary_first_name").val(),
        'beneficiary_last_name': $("#beneficiary_last_name").val(),
        'beneficiary_state': $("#beneficiary_state").val(),
        'beneficiary_postcode': $("#beneficiary_postcode").val(),
        'beneficiary_account_number': $("#beneficiary_account_number").val(),
        'beneficiary_bic_swift': $("#beneficiary_bic_swift").val(),
        'transaction_description': $("#transaction_description").val(),
        'transaction_statement_descriptor': $("#transaction_statement_descriptor").val()
      }, 
      success: function (data, status, xhr) {
        // Show Status
        $("#request-status-error").slideUp();
        $("#request-status-loading").slideUp();
        // Show Success Status with the Payout ID
        $("#request-status-success").append("<br>"+"Payout ID:"+data.id);
        $("#request-status-success").slideDown();

      },
      error: function (jqXhr, textStatus, errorMessage) {
        // Show Error
        $("#request-status-loading").slideUp();
        $("#request-status-error").slideDown();
        console.log('Error' + errorMessage);
      }

    });

  });
});

The file includes two event listeners:

“Pay Salary” button click listener: Shows a loading status, then makes a POST request to the endpoint /get-required-fields to send the data entered in the form. After the request execution, it creates the form fields for the Swift payment method in three sections: beneficiary information, sender information, and transaction details.
“Send Payment” button click listener: Shows a loading status, then makes a POST request to the endpoint /send-payment to send the data entered in the form that will be used as the API request message body. Once the request is executed, it shows a success message with the payout ID, which is retrieved from the JSON response.

Creating the Controller

This controller contains the methods that will handle the Rapyd Disburse API requests. Create a file named payoutController.js in the /controllers directory and paste in the following code:

const {makeRequest} = require('../helpers/utilities');
const dotEnv = require('dotenv');

dotEnv.config();

class payoutController{

    constructor(){

    }

    // Get Swift payment method required fields using Rapyd Disburse API
    static async getRequiredFields(request, response, next){
        try {
            const { 
              sender_country, 
              sender_currency, 
              beneficiary_country, 
              payout_currency, 
              sender_entity_type, 
              beneficiary_entity_type, 
              payout_amount,
            } = request.body;


            const result = await makeRequest('GET', '/v1/payouts/xx_swift_bank/details?sender_country='+sender_country+'&sender_currency='+sender_currency+'&beneficiary_country='+beneficiary_country+'&payout_currency='+payout_currency+'&sender_entity_type='+sender_entity_type+'&beneficiary_entity_type='+beneficiary_entity_type+'&payout_amount='+payout_amount);
            response.json(result.body.data);

          } catch (error) {

            response.json(error);
          }
    }

    // Create Swift payment using Rapyd Disburse API
    static async sendPayment(request, response){
        const walletID = process.env.PAYOUT_WALLET_ID; // Wallet ID

        try {
            const requestBody = {
                "ewallet": walletID,
                "merchant_reference_id": "Test-Cash-8888",
                "payout_amount": request.body.payout_amount,
                "payout_method_type": "xx_swift_bank",
                "sender_currency": "USD",
                "sender_country": request.body.sender_country,
                "beneficiary_country": request.body.beneficiary_country,
                "payout_currency": request.body.payout_currency,
                "sender_entity_type": "company",
                "beneficiary_entity_type": "individual",
                "beneficiary": {
                   "payment_type": "regular",
                   "address": request.body.beneficiary_address,
                   "city": request.body.beneficiary_city,
                   "country": request.body.beneficiary_country,
                   "first_name": request.body.beneficiary_first_name,
                   "last_name": request.body.beneficiary_last_name,
                   "state": request.body.beneficiary_state,
                   "postcode": request.body.beneficiary_postcode,
                   "bic_swift": "573675777",
                   "account_number": request.body.beneficiary_account_number,
               },
               "sender": {
                   "company_name" : "My Company",
                   "address": request.body.sender_address,
                   "city": "Anytown",
                   "state": "NY",
                   "phone_number": "+145434653466"
               },
               "description": request.body.transaction_description,
               "statement_descriptor": request.body.transaction_statement_descriptor,
               "metadata": {
                   "merchant_defined": true
               }
           };

            const result = await makeRequest('POST', '/v1/payouts', requestBody);
            console.log("--------------------------");
            console.log(JSON.stringify(result.body.data));
            response.json(result.body.data);

          } catch (error) {

            response.json(error);
          }
        }

} 

module.exports = payoutController;

The controller has two static asynchronous methods:

getRequiredFields: Makes a GET request to the Rapyd Disburse API to retrieve the required fields for a Swift payment and returns a JSON response.
sendPayment: Makes a POST request to create a Swift payout using the data fetched from the HTML form and the wallet ID fetched from the environment variables in the .env file.

Running and Testing the Application

At this point, you are ready to run your application and test sending a Swift payout. In order to send a Swift payout, you need to create a Rapyd wallet and have sufficient funds in it. You can perform these two actions in the Rapyd sandbox environment.

Create and Fund a Rapyd Wallet

You can perform this action using Postman, and follow the steps to create and fund a wallet with the following request URI:

POST https://sandboxapi.rapyd.net/v1/user

Use this object as the request body:

{
    "first_name": "My Company",
    "ewallet_reference_id": "Test-8888",
    "metadata": {
        "merchant_defined": true
    },
    "type": "company",
    "contact": {
        "phone_number": "+14155588799",
        "email": "sanboxtest@rapyd.net",
        "first_name": "John",
        "last_name": "Doe",
        "contact_type": "business",
        "address": {
            "name": "My Company",
            "line_1": "888 Some Street",
            "city": "Anytown",
            "state": "NY",
            "country": "US",
            "zip": "12345",
            "phone_number": "+14155588799"
        },
        "identification_type": "PA",
        "identification_number": "1234567890",
        "date_of_birth": "11/22/2000",
        "country": "US",
        "nationality": "US",
        "metadata": {
            "merchant_defined": true
        },
        "business_details": {
            "entity_type": "company",
            "name": "My Company",
            "registration_number": "4234567779",
            "industry_category": "company",
            "industry_sub_category": "home services",
            "address": {
                "name": "My Company",
                "line_1": "888 Some Street",
                "line_2": "Suite 1200",
                "city": "Anytown",
                "state": "NY",
                "country": "US",
                "nationality": "IT",
                "zip": "10101",
                "phone_number": "+14155588799",
                "metadata": {
                    "merchant_defined": true
                }
            }
        }
    }
}

The Rapyd wallet ID in the JSON response will look something like this: “ewallet_9b63887ff57f1f8cd906c76d74253979”. Copy the wallet ID from the JSON response and paste it into the .env file.

To deposit funds in your payout sender currency (USD in this case), use the following as the request URI:

POST https://sandboxapi.rapyd.net/v1/account/deposit/

And this JSON object as the message body:

{
  "ewallet": "{YOUR-WALLET-ID-FROM-THE-PREVIOUS-RESPONSE}",  
  "amount": "20000", 
  "currency": "USD",    
  "metadata": {    "merchant_defined": true   }
}

Once you receive a successful response, you are then ready to run and test the application.

Run the Server

Navigate to your project’s main folder in the terminal and run the following command:

nodemon index.js

Go to your browser and open http://localhost:3000/. The homepage should look like this:

For this example, you'll be paying out 400 Euros to someone in France, so use "EUR" as the currency code, "FR" as the country code, and "400" as the payout amount. Then, click the Pay Salary button.

Once the request is completed, the required fields based on the data you entered will appear as shown in the following image:

Note that you have set the sender country to "US" and the sender currency to "USD" in the application code. This is why funding the wallet with USD was required in the previous step.

Because you are using the Rapyd sandbox environment, you can set the account number value to "888******" and the bic_swift value to a random value like "573675777". Then go on filling in the rest of the sender, beneficiary, and transaction details fields. Click the **Send Payment button once you’re finished, and wait a few seconds for the transaction to be done. The success message will show the payment ID as in the following image. You will need this ID to simulate the payment completion action in the next step.

Note: One of the fields that is not required in this example is purpose_code. This field describes the nature of the payout, or what the payout is for. It is only required while sending a payment to one of the following countries: China, India, South Korea, Philippines, and Malaysia. The value of this field can only be one of the following: investment_income, salary, insurance_payments, computer_services, educational_services, payment_of_goods, payment_of_services, or inward_remittance.

Simulating Payment Complete Webhook Action

When the payout is completed and the beneficiary receives the funds, Rapyd sends a webhook that your application can receive. Rapyd's sandbox does not automatically simulate the action of receiving the payout funds. Instead, the Rapyd Disburse API provides a way for you to simulate the payment completion action. In order to do this, you need to define a URL that receives Rapyd Disburse webhooks in your Rapyd dashboard.

To add a webhook in your Rapyd dashboard, you need to have a live URL for your local server that can be accessed online. You can do this by using a third-party service like ngrok. Create an ngrok account and follow their setup guide to have a live URL for your local server.

After installing ngrok and following the setup guide from your account dashboard, run ngrok http 3000 in the terminal window. Then open the tunnels tab in your ngrok dashboard to see the live URL that you created. You'll use this URL to create a webhook. Copy the URL followed by the webhook route like this:

{YOUR-NGROK-URL}/payment-complete

. Paste it into the webhooks page in your Rapyd dashboard, as in the following image, then click “Create”:

Once the webhook is created, click Edit Webhooks next to your the newly created webhook, and add the disburse events.

The payout will usually be in "Confirmation" status awaiting the confirmation of the FX rate. To confirm the FX rate, run the following request and use the payout ID that you received from the form submission in the “payout” parameter:

POST https://sandboxapi.rapyd.net/v1/payouts/confirm/:payout

Finally, make sure that your application server and ngrok are running, then perform the payment completion simulation with this request URI:

POST https://sandboxapi.rapyd.net/v1/payouts/complete/:payout/:amount

Use the same payout ID from the previous request in the “payout” parameter as well as the same payout amount.

Once the request is done successfully, the response will show in your terminal window as coded in the "/payment-complete" route, like this:

Conclusion

In this article, you were introduced to the Swift payment method and the capabilities of the Rapyd Disburse API to send payouts using Swift. Then you learned how to create a Node.js server using Express to make an interface and send payouts using the Rapyd Disburse API, as well as how to use webhooks to listen to and confirm payout transactions upon completion.

The Rapyd Disburse API is designed to help your business pay contractors, workers, suppliers, or any other business anywhere in the world. By using the Rapyd Disburse global payout platform, you can reach 100+ countries using a set of payout methods including bank transfers, eWallets, cards, and cash.

Aside from disbursements, Rapyd also provides a range of global payment solutions, including accepting foreign payments, hosted ecommerce checkout pages, receiving and managing escrow payments, managing global subscriptions, and recurring billing.

Have any thoughts or questions? Post them in the Rapyd Developer Community.

🗞 Rapyd Developer Newsletter: July 2023

Kyle Pollock — Tue, 12 Sep 2023 19:35:31 +0000

Get ready, as we're coming to Berlin for the WeAreDevelopers World Congress on July 27-28th. This is an invaluable chance to delve deep into FinTech, with Rapyd's Founder and CEO, Arik Shtilman, delivering a keynote on "Fintech Rebellion: How Developers are Disrupting the Future of Commerce."

Furthermore, Arik will engage in a fireside chat with Mike Butcher, MBE of TechCrunch, on the first day of the conference — a conversation you won't want to miss!

Be sure to visit our booth during the congress, where you'll have the opportunity to partake in our Checkout Challenge. This not only gives you a chance to demonstrate your abilities but also potentially win a trip to Rapyd's R&D Center in Dubai or Tel Aviv.

Rapyd U Office Hours: Python CLI, Get Daily Rate, Customer Object

Watch the recap of last month’s Rapyd U Office Hours live stream. Learn how to generate a Signature Request in Python and a CLI repository.

Rapyd Developer Community Livestream
Join Rapyd team members and other developers in Discord on Thursday 7/27/23 at 11 AM PDT to learn about the Rapyd API and a short tutorial intro. Come learn about how to integrate with Rapyd, and ask your questions to get help.

Explore our vibrant community today to connect with 54,400 other developers, learn from their experiences, and stay up-to-date with the latest payment technology trends. Collaborate on Rapyd projects and contribute to the payments technology ecosystem while networking with other developers in the fintech industry.

DISCOVER 🔎

Rapyd Changelog: Error Responses, Payout Status Tracker, Creating an Additional Account
Follow recent updates to Error Responses, Payout Status Tracker and more.

Golang Payment Gateway Integration with Rapyd

Learn how to integrate with the Rapyd API using Golang.

Embracing the Power of Collaboration: Unleashing Developer Synergy
Explore a quick article on practices of developer collaboration.

Know Your Business: Who is the Best Fit for Fintech Service Providers?
Learn how the KYB process and business in fintech go hand-in-hand.

Accepting Payments with the Rapyd Collect API: A Use Case for Enterprise Customers
The Rapyd Collect API simplifies the complex process of accepting international payments, making it easier for your business to reach enterprise customers worldwide.

Most Common Errors Using the Rapyd Postman Collection
Are you using Postman to test the Rapyd API? Make sure you avoid these mistakes.

CHANGELOG 📣

SEPA Direct Debit payment methods are now supported on the Hosted Subscription Page, the Hosted Checkout Page and Checkout Toolkit.

The Hosted Subscriptions, Checkout Page and Checkout Toolkit have been updated to include additional call to action selections including Pay and Purchase.

The Checkout Toolkit has been updated to and you can now omit the CTA button from the iframe by passing a hide_submit_button param.

The Developers section in the Client Portal has been updated to include an improved user experience. The Webhooks section has been redesigned to organize each webhook event by each Rapyd product or object including: Collect, Disburse, Issuing Wallets, Protect and the Customer object.

READ THE CHANGELOG

See you next month,

The Rapyd Developer Community Team

How to Email an Invoice After Payments Are Complete

Kyle Pollock — Tue, 15 Aug 2023 20:06:33 +0000

By Kevin Kimani

Invoice management is a process that involves generating, sending, tracking, and reconciling invoices for goods or services that a customer has purchased. Invoice management is significant for e-commerce customers as it allows them to track their financial transactions and ensure that they were billed correctly. It also helps the customers to stay organized and be able to manage their finances more effectively.

Rapyd Collect is an API provided by Rapyd, a fintech company that offers a global payment processing platform. The Rapyd Collect API allows businesses from around the world to easily collect payments from their clients via several payment methods, including bank transfers, bank redirect, card, cash, and local eWallet.

With the Rapyd Collect API, you can build an e-commerce platform that allows you to create a product on Rapyd, collect payments via a Rapyd checkout page, create an invoice for the product purchased, and integrate a mailer service to automatically send the invoice to the customer once the payment is complete.

In this tutorial, you‘ll learn to create and send custom invoices using the Rapyd Collect API. To do so, you will:

Create a Node.js web app that contains a product page
Integrate the Rapyd checkout flow
Use the Rapyd Collect API to create a product (service) in Rapyd, set up a plan and subscription, and create an invoice containing the items that the client subscribes to
Integrate a mailer service (Mailgun) to automatically send the invoice to the client once the payments are complete

You can find the code for this tutorial in this GitHub repo.

Implementing Automated Invoice Emails After Payment

To follow along in implementing the system described above, you’ll need:

Node.js, npm, a code editor, and a browser installed on your local machine.
A Rapyd account.
Postman set up on your local machine. You can also use the web version.
A Mailgun account. Sign up for a free trial and be sure to verify your email.

You also need to head over to the Rapyd Docs and learn how to make your first API call.

Setting Up the Development Environment

To get started, create a folder called rapyd-invoice. Open it in your code editor and run the following command in the terminal:

npm init -y

This command will initialize a Node.js project in the rapyd-invoice directory and create a package.json file. Next, run the command below to install the dependencies that will be used in this project:

npm i express dotenv ejs node-persist nodemon body-parser mailgun-js

These dependencies include:

express - to set up a Node.js server.
dotenv - to load environment variables.
ejs- to serve as the templating engine.
node-persist - to create local storage on the server.
nodemon - to monitor changes in the server code and restart it automatically.
body-parser - to parse incoming request bodies.
mailgun-js - to mail the invoice to the customer.

Next, modify the package.json scripts key-value pair with the following to include a command to start the server:

  "scripts": {
    "start": "nodemon index.js"
  },

Then create a utils.js file in the project root folder and add the code below, which is provided by Rapyd to help in interacting with their APIs:

require('dotenv').config({path: './.env'});

const https = require('https');
const crypto = require('crypto');
const accessKey = process.env.RAPYD_ACCESS_KEY
const secretKey = process.env.RAPYD_SECRET_KEY
const log = false;

async function makeRequest(method, urlPath, body = null) {

    try {
     httpMethod = method;
     httpBaseURL = "sandboxapi.rapyd.net";
     httpURLPath = urlPath;
     salt = generateRandomString(8);
     idempotency = new Date().getTime().toString();
     timestamp = Math.round(new Date().getTime() / 1000);
     signature = sign(httpMethod, httpURLPath, salt, timestamp, body)

     const options = {
         hostname: httpBaseURL,
         port: 443,
         path: httpURLPath,
         method: httpMethod,
         headers: {
             'Content-Type': 'application/json',
             salt: salt,
             timestamp: timestamp,
             signature: signature,
             access_key: accessKey,
             idempotency: idempotency
         }
     }

     return await httpRequest(options, body, log);
    }
    catch (error) {
     console.error("Error generating request options");
     throw error;
    }
}

function sign(method, urlPath, salt, timestamp, body) {

    try {
     let bodyString = "";
     if (body) {
         bodyString = JSON.stringify(body);
         bodyString = bodyString == "{}" ? "" : bodyString;
     }

     let toSign = method.toLowerCase() + urlPath + salt + timestamp + accessKey + secretKey + bodyString;
     log && console.log(`toSign: ${toSign}`);

     let hash = crypto.createHmac('sha256', secretKey);
     hash.update(toSign);
     const signature = Buffer.from(hash.digest("hex")).toString("base64")
     log && console.log(`signature: ${signature}`);

     return signature;
    }
    catch (error) {
     console.error("Error generating signature");
     throw error;
    }
}

function generateRandomString(size) {
    try {
     return crypto.randomBytes(size).toString('hex');
    }
    catch (error) {
     console.error("Error generating salt");
     throw error;
    }
}

async function httpRequest(options, body) {

    return new Promise((resolve, reject) => {

     try {

         let bodyString = "";
         if (body) {
             bodyString = JSON.stringify(body);
             bodyString = bodyString == "{}" ? "" : bodyString;
         }

         log && console.log(`httpRequest options: ${JSON.stringify(options)}`);
         const req = https.request(options, (res) => {
             let response = {
                 statusCode: res.statusCode,
                 headers: res.headers,
                 body: ''
             };

             res.on('data', (data) => {
                 response.body += data;
             });

             res.on('end', () => {

                 response.body = response.body ? JSON.parse(response.body) : {}
                 log && console.log(`httpRequest response: ${JSON.stringify(response)}`);

                 if (response.statusCode !== 200) {
                     return reject(response);
                 }

                 return resolve(response);
             });
         })

         req.on('error', (error) => {
             return reject(error);
         })

         req.write(bodyString)
         req.end();
     }
     catch(err) {
         return reject(err);
     }
    })

}

exports.makeRequest = makeRequest;

Next, create an .env file in the project root folder and paste the following content:

RAPYD_ACCESS_KEY=
RAPYD_SECRET_KEY=
MAILGUN_API_KEY=
MAILGUN_DOMAIN=
MAILGUN_SENDER_EMAIL=

To get the values for the Rapyd access and secret keys, follow the instructions provided here under Get Your API Keys.

To get the values for the Mailgun fields, log into your Mailgun account and click on Sending on the sidebar. Select Domains, copy the domain provided, and assign it to MAILGUN_DOMAIN.

Next, click on your account name in the top right corner. In the dropdown that appears, select API keys. Copy the value of Private API key and assign it to MAILGUN_API_KEY.

For the MAILGUN_SENDER_EMAIL, use the email you used to create your Mailgun account.

Finally, create an index.js file in the project root folder and add the code below to create a basic Express server:

// import the required dependencies
require('dotenv').config({path: './.env'});

const express = require('express')
var bodyParser = require('body-parser')
const storage = require('node-persist');

var mailgun = require('mailgun-js')({apiKey: process.env.MAILGUN_API_KEY, domain: process.env.MAILGUN_DOMAIN});

storage.init()

const app = express()

// set the port
const port = 3000

// import the utility file for making requests to the Rapyd API
const makeRequest = require('./utils').makeRequest;

// variables
const planId = "<your-plan-id>"

//set the render engine
app.set("view engine", "ejs")

// parse application/json
app.use(bodyParser.json())

//Add routes here

app.listen(port, () => {
    console.log(`Example app listening on port ${port}`)
  })

You can confirm that the server is running successfully by running the following command in the terminal:

npm start

Creating the Product Page

The product page will show the details of the service, as well as a form where the customer will input their details. Before implementing this page, you’ll need to create a product and a plan in Rapyd.

With Rapyd, a product can be of type goods or service. For this tutorial, you’ll be creating a service product. To learn more about goods, you can check out the official documentation. A service product needs to be attached to a plan that describes the pricing structure of the service. The plan is then attached to a subscription.

To create a product of type service, you will use the Rapyd Postman collection. Open the collection in either Postman for Web or the Postman app installed on your local machine.

Once you load the collection, you should have something similar to this:

Next, you need to create a Rapyd environment containing the Rapyd access and secret keys, as well as the base uri where you will be sending the API requests. Click on Environments in the left sidebar and create a new environment containing the required fields. You should end up with something like this:

Then head back to the Collections tab and load the newly created environment in the top right corner:

Next, from the Rapyd API Collection, search for "create services". From the results, click on Create Services, and in the tab that opens, send a POST request with the following request body:

{
    "id": "",
    "name": "Monthly Parking Service Booking",
    "type": "services",
    "active": true,
    "description": "Sign up for our monthly parking service and enjoy the convenience of having a guaranteed spot every day",
    "images": [
     "https://images.unsplash.com/photo-1506521781263-d8422e82f27a?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1170&q=80"
    ],
    "shippable": false,
    "statement_descriptor": "",
    "unit_label": ""
}

More information about each of these fields is discussed in the official documentation.

From the response received, copy data.id, which represents the product_id, as it will be used to create a plan.

To create a plan, you’ll use Postman. From the Rapyd API collection, search for "create plan". From the search results, select the Create plan with product ID option. From the tab that opens, send a POST request with the following request body:

Remember to replace your-product-id with the corresponding product ID that you received from the previous step.

{
    "currency": "USD",
    "interval": "month",
            “amount”: 1150,
    "product": "your-product-id",
    "aggregate_usage": "",
    "billing_scheme": "per_unit",
    "nickname": "basic",
    "transform_usage": {},
    "trial_period_days": 0,
    "usage_type": "licensed"
}

More information about each of these fields is discussed in the official documentation.

Copy the plan ID from the response, as you will use it to query the plan and the product and display the data on a web page. Open the index.js file and assign your plan ID to the const planId that has been defined already.

Now you can create a route to query for the product and plan information and return it to the frontend. Add the following code to the index.js file:

Make sure you add the code before the app.listen() function.

// Route to query the plan and return plan+product details
app.get('/', async (req, res) => {
    try {
     const { body: { data } } = await makeRequest('GET', `/v1/plans/${planId}`);

     await storage.setItem('productPrice', data.amount)

     res.render('product', {
         title: data.product.name,
         price: data.amount,
         description: data.product.description,
         image: data.product.images[0]
     })
    } catch (error) {
     console.log(error)
    }
})

In the code above, you:

Make a GET request to the Rapyd Collect API to retrieve the plan information.
Save the product price to the local storage.
Extract the required data and return it to the client along with the template that will be rendered when a request is made to this route.

To create the product template, create a folder called views in the project root folder. Inside it, create a product.ejs file and add the following code:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Product Page</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
    <style>
     .hidden{
         display: none;
     }
    </style>
</head>
  <body class="container-sm text-center">
    <!-- Display product -->
    <div class="mt-3 d-flex flex-row">
     <img src=<%=image%> alt="Product image" style="max-width: 450px;">

     <div class="px-5 py-3 text-start d-flex flex-column justify-content-between align-items-start">
         <h2 class="title"><%=title%></h2>
         <p class="description"><%=description%></p>
         <p class="price"><strong>Price:</strong> $<%=price%> (Billed monthly)</p>
         <button class="btn btn-primary" id="purchaseBtn">Book Now</button>
     </div>
    </div>

    <!-- Customer details form -->
    <div class="mt-5 hidden" id="custContainer">
     <hr>
     <h3>Customer Details</h3>
     <form class="text-start row g-3">
         <h5>Personal Details</h5>
         <div class="col-md-4">
             <label for="custName" class="form-label">Name</label>
             <input type="text" class="form-control" id="custName" value="Jane Doe">
         </div>
         <div class="col-md-4">
             <label for="custEmail" class="form-label">Email</label>
             <input type="text" class="form-control" id="custEmail">
         </div>
         <div class="col-md-4">
             <label for="custPhone" class="form-label">Phone</label>
             <input type="text" class="form-control" id="custPhone" value="+14155559993">
         </div>

         <h5>Payment Details</h5>
         <div class="col-3">
             <label for="custCardNo" class="form-label">Card Number</label>
             <input type="text" class="form-control" id="custCardNo" placeholder="4111 1111 1111 1111" value="4111111111111111">
         </div>
         <div class="col-3">
             <label for="custCardExpMonth" class="form-label">Expiry Month</label>
             <input type="number" class="form-control" id="custCardExpMonth" placeholder="12" value="12">
         </div>
         <div class="col-3">
             <label for="custCardExpYear" class="form-label">Expiry Year</label>
             <input type="number" class="form-control" id="custCardExpYear" placeholder="34" value="34">
         </div>
         <div class="col-3">
             <label for="custCardCVV" class="form-label">CVV</label>
             <input type="number" class="form-control" id="custCardCVV" placeholder="567" value="567">
         </div>

         <div class="col-12">
             <button type="submit" id="checkoutBtn" class="btn btn-primary">Checkout</button>
         </div>
         </form>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-kenU1KFdBIe4zVF0s0G1M5b4hcpxyD9F7jL+jjXkk+Q2h455rYXK/7HAuoJl+0I4" crossorigin="anonymous"></script>
    <script>
     const purchaseBtn = document.getElementById('purchaseBtn')
     const custContainer = document.getElementById('custContainer')
     const checkoutBtn = document.getElementById("checkoutBtn")

     purchaseBtn.addEventListener('click', () => {
         custContainer.classList.remove('hidden')
         purchaseBtn.setAttribute('disabled', 'true')
         purchaseBtn.innerText = 'Provide your details below'
     })

     custContainer.addEventListener('submit', (e) => {
         e.preventDefault()

         const customerDetails = {
         name: document.getElementById('custName').value,
         email: document.getElementById('custEmail').value,
         phone: document.getElementById('custPhone').value,
         cardNo: document.getElementById('custCardNo').value,
         cardExpMonth: document.getElementById('custCardExpMonth').value,
         cardExpYear: document.getElementById('custCardExpYear').value,
         cardCVV: document.getElementById('custCardCVV').value
     }

         console.log(customerDetails)

         fetch('http://localhost:3000/', {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json'
             },
             body: JSON.stringify({
                 customerDetails: customerDetails
             })
         }).then(res => {
           console.log(res)
           if(res.status === 200){
               window.location.assign('http://localhost:3000/checkout')
           }
     })

     })
    </script>
  </body>
</html>

The code above renders a template that displays the product information. It also has a button called Book Now, which, when clicked, displays a form for the customer to fill in their details. The form has a Checkout button, which sends the form data to the server and redirects the customer to the /checkout route when clicked.

Next, you need to create a route that will receive these customer details and use them to create a customer on Rapyd. Open index.js and add the following route:

// Route to receive client details and create a customer on Rapyd
app.post('/', async (req, res) => {
    //create a customer using the payment details from the request body
    try {
    const body = {
      name: req.body.customerDetails.name,
      email: req.body.customerDetails.email,
      phone_number: req.body.customerDetails.phone,
      payment_method: {
     type: 'us_debit_visa_card',
     fields: {
         number: req.body.customerDetails.cardNo,
         expiration_month: req.body.customerDetails.cardExpMonth,
         expiration_year: req.body.customerDetails.cardExpYear,
         cvv: req.body.customerDetails.cardCVV
     }
      }
    }
    const { body: { data } }  = await makeRequest('POST', '/v1/customers', body)

    await storage.setItem('customerId', data.id)
    await storage.setItem('defaultPaymentMethod', data.default_payment_method)
    await storage.setItem('customerEmail', data.email)

    res.status(200).json({ success: true })

    } catch (error) {
      console.log(error)
    }
})

The code above creates a customer with a default payment method. From the API response, it extracts the customer ID, default payment method, and customer email and saves the details to local storage.

Creating the Checkout Page

Rapyd Checkout is available as a [hosted page]https://docs.rapyd.net/en/hosted-checkout-page-integration.html) and as a toolkit. This tutorial implements the checkout toolkit integration.

To create a checkout page, you first have to make a POST request to the Rapyd Collect API with the required fields. From the API response, you need to extract the checkout ID and send it to the frontend. For the expiration date, make sure you add a future date (epoch timestamp) that is not more than one year from today’s date. To do so, add the following code to your index.js file:

// Route to create a checkout page and return the checkout ID to the client
app.get('/checkout', async (req, res) => {
    let customerId = await storage.getItem('customerId')
    let productPrice = await storage.getItem('productPrice')

    try {
     const body = {
         amount: productPrice,
         country: 'US',
         currency: 'USD',
         customer: customerId,
         language: 'en',
         expiration: 1704019927,
     };

     const { body: { data }} = await makeRequest('POST', '/v1/checkout', body);

     res.render('checkout', {
         checkoutId: data.id
      })

      } catch (error) {
     console.error('Error completing request', error);
      }
})

Next, create a file called checkout.ejs in the views folder and paste in the code below:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Checkout Page</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
</head>
  <body class="container-sm text-center">
    <div class="cont">
     <h1>Checkout page</h1>

     <!-- iframe -->
     <div id="rapyd-checkout"></div>
    </div>

    <!-- code to display the iframe -->
    <script src="https://sandboxcheckouttoolkit.rapyd.net"></script>
    <script>
     window.onload = function () {
         let checkout = new RapydCheckoutToolkit({
             pay_button_text: "Click to pay",
             pay_button_color: "blue",
             id: "<%=checkoutId%>"
         });
         checkout.displayCheckout();
     }
     window.addEventListener('onCheckoutPaymentSuccess', function (event) {
         console.log(event.detail)
         console.log(typeof(event.detail.status))
         alert('payment successful')

         window.location.assign('http://localhost:3000/verification')

     });
     window.addEventListener('onCheckoutPaymentFailure', function (event) {
         console.log(event.detail.error)
         alert('error while processing your payment')
     });
    </script>
  </body>
</html>

The code above uses the checkoutId from the server to render a checkout page containing the details of the customer and the amount to be paid.

On successful payment, the page displays an alert message: "payment successful". When the customer clicks on the OK button, they are redirected to the verification page.

Creating the Verification Page

On this page, the customer needs to perform 3DS authentication. Since this guide covers working in the sandbox, 3DS authentication will only be simulated. 3DS authentication is only relevant where the payment method is card. The Rapyd 3DS simulator helps to authenticate the card so that the payment can be completed.

To render a verification page when the customer is navigated there, add the following route to the index.js file:

app.get('/verification', async (req, res) => {
    let customerId = await storage.getItem('customerId')
    let defaultPaymentMethod = await storage.getItem('defaultPaymentMethod')

    // Create subscription
    try {
     const subscriptionBody = {
         customer: customerId,
         billing: 'pay_automatically',
         billing_cycle_anchor: '',
         cancel_at_period_end: true,
         coupon: '',
         days_until_due: null,
         payment_method: defaultPaymentMethod,
         subscription_items: [
         {
             plan: planId,
             quantity: 1
         }
         ],
         tax_percent: 10.5,
         plan_token: ''
     };

     const { body: { data }} = await makeRequest('POST', '/v1/payments/subscriptions', subscriptionBody);

     await storage.setItem('subscriptionId', data.id)

     // create invoice
     try {
         let subscriptionId = await storage.getItem('subscriptionId')
         const invoiceBody = {
             customer: customerId,
             billing: 'pay_automatically',
             days_until_due: null,
             description: '',
             due_date: 0,
             metadata: {
             merchant_defined: true
             },
             statement_descriptor: '',
             subscription: subscriptionId,
             tax_percent: '',
             currency: 'USD'
         };
         const { body: { data }} = await makeRequest('POST', '/v1/invoices', invoiceBody);

         await storage.setItem('invoiceId', data.id)

         console.log(data);

         // create invoice items
         try {
             let customerId = await storage.getItem('customerId')
             let invoiceId = await storage.getItem('invoiceId')
             let subscriptionId = await storage.getItem('subscriptionId')
        let productPrice = await storage.getItem('productPrice')

             const invoiceItemBody = {
                 currency: 'USD',
                 customer: customerId,
                 invoice: invoiceId,
                 plan: planId,
                 metadata: {
                 merchant_defined: true
                 },
                 amount: productPrice
             };
             const { body: { data }} = await makeRequest('POST', '/v1/invoice_items', invoiceItemBody);

             console.log(data);
             } catch (error) {
             console.error('Error completing request', error);
             }
         } catch (error) {
         console.error('Error completing request', error);
         }
         } catch (error) {
     console.error('Error completing request', error);
      }

    // finalize invoice
    let invoiceId = await storage.getItem('invoiceId')
    try {
     const { body: { data }} = await makeRequest(
         'POST',
         `/v1/invoices/${invoiceId}/finalize`
     );

     console.log(data);

     res.render('verification', {
         authLink: data.payment.redirect_url
     })

      } catch (error) {
     console.error('Error completing request', error);
      }
})

In the code above, you:

Create a subscription and save the subscriptionId from the API response in local storage.
Create an invoice using the subscriptionId and save the invoiceId from the API response in local storage.
- Note: An invoice has a few statuses, as discussed here under the Response Parameters. The invoice you just created is in a draft state. In this state, you edit the invoice and add invoice items. You will later finalize the invoice to mark it as "paid" and complete the payment associated with it.
Create invoice items using the invoiceID and add them to the invoice.
Finalize the invoice by making a POST request with the invoiceId. From the API response received, you extract the redirect_url to simulate 3DS authentication and send it to the front end.

Next, you need to create the verification page that the customer can use to simulate 3DS authentication. Create a verification.ejs file in the views folder and add the code below:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Verification Page</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
</head>
  <body class="container-sm text-center">
    <div class="cont">
     <h1>3DS Verification</h1>
     <!-- <p>Open the link below in a new page to simulate 3DS authentication</p> -->
     <p>
         <a href="<%=authLink%>" target="_blank" id="auth">Simulate 3DS Authentication</a>
     </p>
     <p>Once you're done, come back to this page and select "Generate Invoice".</p>
     <button class="btn btn-primary" id="generateBtn" disabled>Generate Invoice</button>
    </div>

    <script>
     const generateBtn = document.getElementById('generateBtn')

     document.getElementById('auth').addEventListener('click', () => {
         generateBtn.removeAttribute('disabled')
     })

     generateBtn.addEventListener('click', () => {
         window.location.assign('http://localhost:3000/invoice')
     })
    </script>
  </body>
</html>

The code above renders an HTML file that instructs the customer to click the link displayed, perform 3DS simulation, and then return to the page and click the Generate Invoice button. This button redirects the customer to the invoice page.

Creating the Invoice Page

This page will display the invoice data to the customer. To create it, you first need the server code to retrieve the invoice and the invoice items. Open index.js and add the following route:

// Retrieve invoice, line items => return line items to client
app.get('/invoice', async (req, res) => {
    let custEmail = await storage.getItem('customerEmail')

    let item
    let quantity
    let subTotal
    let tax
    let total
    let status

    // retrieve invoice
    try {
     let invoiceId = await storage.getItem('invoiceId')

     console.log(invoiceId)

     const { body: { data }} = await makeRequest(
         'GET',
         `/v1/invoices/${invoiceId}`
     );

     console.log(data)

     quantity = data.lines.length
     subTotal = data.subtotal
     tax = data.tax
     total = data.total
     status = data.status

     // retrieve subscription
     try {
         const subscriptionId = await storage.getItem('subscriptionId')
         const { body: { data }} = await makeRequest(
             'GET',
             `/v1/payments/subscriptions/${subscriptionId}`
         );

         item = data.subscription_items.data[0].plan.product.name;

         // console.log(data.subscription_items.data[0].plan.product)

         } catch (error) {
         console.error('Error completing request', error);
         }
      } catch (error) {
     console.error('Error completing request', error);
      }

      // send email
      let invoiceId = await storage.getItem('invoiceId')
      var data = {
      from: `Monthly Booking Services <${process.env.MAILGUN_SENDER_EMAIL}>`,
      to: custEmail,
      subject: 'Monthly Booking Services Invoice',
      html: `<h1>Monthly Booking Services</h1><h3>Your Invoice ID: ${invoiceId}</h3><p>Item: ${item}</p><p>Quantity: ${quantity}</p><p>Tax: ${tax}</p><p>Total: ${total}</p><p>Invoice status: ${status}</p>`
      };

      mailgun.messages().send(data, function (error, body) {
     if(error){
         console.log(error)
     }
      console.log(body);
      });

      res.render('invoice', {
     item,
     quantity,
     subTotal,
     tax,
     total,
     status,
     custEmail
      })
})

The code above retrieves the invoice and the subscription associated with the invoice to extract the name of the product the customer has subscribed to. All this information is then returned to the front end. The code also includes the logic to send the invoice details to the customer’s email via Mailgun.

Create a file called invoice.ejs inside the views folder and add the following code to render a page that displays the invoice data to the customer:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Invoice Page</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-rbsA2VBKQhggwzxH7pPCaAqO46MgnOM80zW1RWuH61DGLwZJEdK2Kadq2F9CUG65" crossorigin="anonymous">
</head>
  <body class="container-sm text-center">
    <div class="cont">
     <h2>Your Invoice</h2>
     <table class="table">
         <thead>
             <tr>
             <th scope="col">#</th>
             <th scope="col">Item</th>
             <th scope="col">Quantity</th>
             <th scope="col">Rate</th>
             </tr>
         </thead>
         <tbody>
             <tr>
             <th scope="row">1</th>
             <td><%=item%></td>
             <td><%=quantity%></td>
             <td>$<%=subTotal%></td>
             </tr>

             <tr>
             <td colspan="3" class="text-end">Sub Total</td>
             <td>$<%=subTotal%></td>
             </tr>
             <tr>
             <td colspan="3" class="text-end">Tax</td>
             <td>$<%=tax%></td>
             </tr>
             <tr>
             <td colspan="3" class="text-end">Total</td>
             <td>$<%=total%></td>
             </tr>
             <tr>
             <td colspan="3" class="text-end">Invoice Status</td>
             <td class="bg-success text-white"><%=status%></td>
             </tr>
         </tbody>
         </table>

         <p class="bg-primary text-white py-4 px-2">Invoice successfully sent to: <%=custEmail%></p>
    </div>
  </body>
</html>

Testing the Application

To confirm that the application is working as expected, run npm start in the terminal and open http://localhost:3000 on your browser. You should see the product page:

When you click the Book Now button, the customer details form, which contains some placeholder values for testing purposes, is displayed:

Enter the customer email (make sure to use your own personal email that you used to register your Mailgun account) and click on the Checkout button. You will be redirected to the Checkout page. Once you’re there, select the Click to pay button and click OK on the alert upon successful payment.

This will redirect you to the verification page. Select Simulate 3DS Authentication.

This opens a new tab. Enter the code provided and click the Continue button.

Navigate back to the verification page and select Generate Invoice. This will redirect you to the invoice page and inform you that an email has been sent to the customer's email.

Open your inbox and you should see the received email.

Conclusion

In this article, you learned about Rapyd and the Rapyd Collect API. You also learned about various Rapyd Collect concepts, such as products, plans, subscriptions, invoices, and invoice items. Lastly, you learned how to combine all these concepts to create a web app that automatically sends an invoice to the customer once payments are complete via a mailer service.

Rapyd is a payment processing solution that helps you liberate global commerce with all the tools you need for payments, payouts, and business everywhere. It aims to make it easier for businesses to expand globally by simplifying the process of accepting and making payments in different countries and currencies. Rapyd’s developer-friendly API allows businesses to easily integrate their payment systems with the Rapyd network.

Rapyd Unleashes Fintech Insights at WeAreDevelopers World Congress 2023

Kyle Pollock — Thu, 03 Aug 2023 21:23:22 +0000

Berlin, July 27-28, 2023 — WeAreDevelopers World Congress 2023 witnessed a whirlwind of developers coming together in a vibrant community, alongside insightful lessons and fun competition. The event, attended by over 11,000 developers from across the globe, featured many speakers including from Stripe, Stackoverflow, Github and several leaders across industries.

In a display of boldness, and direct vision, Arik Shtilman, the CEO and Co-Founder of Rapyd, took the stage to talk about Rapyd’s expansion to over hundreds of countries in the global market from a single consumer mobile app that failed. With his own persistent energy, Shtilman painted a vivid picture of the fintech revolution and how developers are at the forefront of disrupting the future of commerce. Every business accepts or moves funds through their platform, and are a part of a critical fintech value exchange. Drawing inspiration from the words of tech luminary Marc Andreessen, Shtilman set the tone sharing how powerful AI will become to shape our workforce—those who tell computers what to do and those who are told what to do by computers. Arik also emphasized at the pace we have seen the global digital commerce in the last three years, the next decade driven by Fintech and Artificial Intelligence is exponentially larger.

Fintech: The Fourth Universal Platform

As Arik delved into the core of his keynote, it became evident that fintech is not just a buzzword; it is a driving force behind the evolution of commerce. The impact of fintech is evident in every corner of the digital world, from online gaming to marketplaces, and from ride-sharing to entertainment platforms. From internet connectivity to cloud software as a service, to mobile ubiquity and now the new frontier of fintech—Shtilman asserted that fintech has now become the fourth platform, powering the value exchange and movement of funds across all aspects of our lives.

Arik also led a firesite sitting down with Mike Butcher, the Editor in Chief TechCrunch EU. Both discussed fintech disruption, and how companies that have partnered with fintech solutions have been greatly successful, and what the future will hold for businesses integrating payments.

A Thrilling Competition: Rapyd Checkout Challenge

On the conference exhibit floor, Rapyd rolled out a realm of excitement and competition with a Rapyd Checkout Challenge for attendees. As Rapyd held the checkout challenge right in the exhibit area, attendees were drawn by the alluring prize—an opportunity to visit one of the Rapyd developer centers. All developers were invited to put their skills to use and test their technical prowess in creating quick and user-friendly checkout processes.

The competition ignited a sense of camaraderie among participants, as developers worked diligently on the integration, filling in any open seats throughout the Rapyd exhibit area. It was a gathering of creativity and problem-solving, with each participant working through their unique knowledge in API integrations, Request Signatures and fintech.

WeAreDevelopers also hosted a coding competition called CODE100, in which participants would compete for a grand prize by testing their technical proficiency, creativity, and problem-solving abilities. Teams worked with APIs, answered questions in coding quizzes, and completed team-work based challenges.

Rapyd Sessions: Payouts, Developer Experience, and Rapyd API Integration

Rapyd's exhibit was not only filled with competition, but also an immersive learning experience by hosting sessions that involved live demos and developer tips to build with fintech. Rapyd's different sessions that delved into usefulness of global payouts, the developer experience, and the seamless integration with the Rapyd API.Developers and industry enthusiasts gathered to learn from each Rapyd speaker about the products, resources, and insights into Rapyd’s developer friendly platform.

Amit Cohen, Director of Product, Dev Rel & Channels, and Nirit Markovich, Product Manager of Developer Platform shared about the Rapyd developer experience—underscoring Rapyd's commitment to empowering developers with a seamless and rewarding journey. The session revealed insights into Rapyd's developer-friendly tools, documentation, and support, ensuring developers have everything they need to unlock fintech potential with ease.

Shaul Efraim, Software Architect at Rapyd hosted a few developer sessions about the power of payouts as well as how to integrate with the Rapyd API. Attendees learn how to get started with fintech, and how Rapyd's powerful API suite unlocks a world of possibilities. Shaul offered hands-on guidance and real-life use cases, illustrating the transformative impact of integrating with the Rapyd ecosystem.

Further talks were led by Mark Khotin, R&D Tech Lead, and Shiri Sadeh, Developer at Rapyd. Live demos included integration with the Rapyd API using code samples as well no code solutions using the Rapyd Client Portal and Plugins.

A Future Fueled by Fintech Innovators

As the event drew to a close, attendees expressed their enjoyment and gratitude for being part of the WeAreDevelopers community. The conference served as a platform for familiar faces to reunite and for new connections to be made, creating a larger network of developers eager to support one another.

With hearts full of inspiration, attendees bid farewell to one another, carrying with them new ideas, invaluable insights, and a sense of belonging to a global community of developers. The event's success reaffirmed the power of collaboration, the potential of technology to drive positive change, and the journey for each individual developer that can often cross paths with other developers from all corners of the world.

If you want to start building you can sign up in the Rapyd Client Portal to begin testing with Rapyd, the one platform to accept, send and hold funds globally.

🗞 Rapyd Developer Newsletter: June 2023

Kyle Pollock — Tue, 18 Jul 2023 19:16:17 +0000

Rapyd U Office Hours: Request Signature, CURL, Evolution of Payments
Watch the recap of last month’s Rapyd U Office Hours live stream. Learn how to generate a Signature Request in Python and CURL.

Rapyd Developer Community Livestream

Join Rapyd team members and other developers in Discord on Thursday 6/29/23 at 11 AM PDT to learn about the Rapyd API, and a short tutorial intro. Come learn about how to integrate with Rapyd, and ask your questions to get help.

Rapyd Developer Bug Bounty
Calling all developers to pressure test the Rapyd API, security and systems. Sign up through the Client Portal, obtain your API keys, and begin testing through any integration method.

DISCOVER 🔍

Rapyd Changelog: Error Responses, Payout Status Tracker, Creating an Additional Account
Follow recent updates to Error Responses, Payout Status Tracker and more.

Why Choose Rapyd: The Rising Star in API-First Companies
Learn why Rapyd can be your all-in-one solution for fintech.

Guide to Building, Validating, and Styling Flutter Forms
Learn how to quickly build and style forms using Flutter.

Payment Methods with FX
Learn how different bank payment methods work with FX.

Cross-Border Payments
Watch and follow along with a cross-border payment.

Handling Trial Periods with the Rapyd Collect API
Create a subscription payment with trial periods with the Rapyd API.

CHANGELOG 📣

The Rapyd API has been updated to allow clients to simulate error responses for Redirect Payments and the Toolkit in Sandbox.

The Hosted Payout Tracker page has been updated to now include an estimated date of arrival of funds for the beneficiary, or recipient.

The create payout process has been updated to allow the sender to fix the sender details while creating a payout.

Following the development for multi-merchant clients. Clients can now create another Rapyd account with their existing user.

Read the Docs

Thanks for reading,

The Rapyd Community Team 👋

Skip the noise and get Rapyd's latest developer news and fintech education straight to your inbox. Sign up now.

Golang Payment Gateway Integration with Rapyd

Kyle Pollock — Mon, 17 Jul 2023 16:27:45 +0000

By Christoph Berger

Integrating a purchase flow into a web application can be complicated. Whether you want to sell a single item or service online or build a full-fledged web shop, you need a payment gateway, which enables the secure processing of electronic payments between a merchant and a payment processor (ie a bank or a credit card company). A payment gateway sends the transaction information from the customer to the acquiring financial institute for authorization and then sends the response back to the merchant.

Payment gateways like Rapyd provide additional benefits, including increased security for sensitive financial information, improved reliability of payment processing, ease of integration, and advanced fraud detection and prevention capabilities. Rapyd is a certified PCI DSS Level 1 service provider.

In this article, you'll focus on a particular benefit: the ease of integration. You'll learn how to build payment processing into your app in a few easy steps using the Rapyd Collect API.

What Is the Rapyd Collect API?

If you're looking for a positive buying experience for your customers with endpoints for payments, products, subscriptions, coupons and discounts, orders, and invoices, the Rapyd Collect API has you covered. This API takes care of collecting payments from customers into Rapyd Wallet, a central component for receiving, storing, and sending money. The Rapyd Collect API provides endpoints for payments, products, subscriptions, coupons and discounts, orders, invoices, and of course, endpoints for easy checkout process integration, which you'll learn more about in the following sections.

For the checkout flow you'll be working on here, you need only access the checkout page endpoints. The Checkout Page API provides two ways of integrating the checkout:

The hosted checkout page integration is an all-in-one solution. This means Rapyd generates the checkout page for you, and you need only supply the amount, the customer's country, the currency, and other optional data (if desired), then Rapyd manages the rest of the checkout flow. The hosted checkout page is not only convenient but also available for clients who have no PCI certification.

The checkout toolkit integration is a more advanced alternative. It's useful if you want to have more control over your layout and user experience by embedding checkout fields directly into your shopping cart page.

Implementing a Payment Gateway Integration in a Go App

In this section, you'll be taught how to write a Go web app with a checkout flow. Before you begin, you'll need to know how to write Go and use the Go toolchain. However, you don't need to have any familiarity with the Rapyd API.

You can follow along using the Rapyd-Samples/accept-payments repository. The go directory contains the complete demo app that you'll be building here.

Alternatively, you can implement all the steps directly by copying the code snippets from the article into a single file. Be sure to start this file with the package declaration and a list of required imports.

package main

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io"
    "log"
    "math/rand"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

Note that if you decide to put the code snippets into multiple files, each file needs only a subset of imports. A Go-aware editor can add and remove imports automatically as needed.

For this example, you'll be building a small woolen-sock web shop that sells only one kind of socks. This means the home page will show the shopping basket right away. The user will be able to select the number of items they want to buy and then head to the checkout. This triggers the app to call the Create Checkout Page endpoint, which will create a new checkout page based on the total price of the items, the user's country, and the currency used.

Then, Rapyd takes over and handles the checkout until the user either completes or cancels the checkout flow. At that point, the flow is transferred back to the web shop.

You'll be building the app from the bottom up, so let's begin!

Set Up the Project

Create a new folder, cd into it, and run the following command:

go mod init rapyd-accept-payments

If you plan to publish your project on GitHub, GitLab, or another repository host, use the full repository path instead of rapyd-accept-payments to enable the use of go install with the remote repository.

Get the Rapyd API Access Key and Secret Key

If you don't already have a Rapyd account, follow the prompts to sign up for one now.

Rapyd provides a sandbox mode for safe API development. After signing up or logging in, enable the sandbox mode by toggling the switch at the top of the page before you continue.

Then, navigate to Developers > Credential Details. Copy the two keys and set them as an environment variable in your shell.

export RAPYD_ACCESS_KEY=<your access key here>
export RAPYD_SECRET_KEY=your secret key here>

This is for bash syntax. For other shells, the syntax may differ.

Your app will fetch these keys from the process environment when accessing the Rapyd API.

Customize the Checkout Page

This step is optional because the hosted checkout page works right out of the box. However, while you're in the developer portal, you can check out the various options for customizing the checkout page to match your company branding.

To customize the checkout page, go to Settings > Branding. Here, you can adjust the look and feel for any hosted page, including the checkout page.

You could add your company logo, adjust the highlight color to match your company's color scheme, select the accepted payment methods, check the text on the Place Your Order button, or add customer support contact details. The changes are immediately visible in the preview area, which shows both desktop and mobile views.

Set Up the API Client

At this point in the tutorial, you're going to work with the API client, which contains the API authentication mechanism. Rapyd uses an advanced authentication scheme that generates a unique signature for every request that verifies the requester and also protects data from being tampered with in transit. This approach is far superior to using (semi-)static access tokens that can only verify the requester but not protect the data.

To authenticate, you need the two keys you acquired earlier, a timestamp, a salt, and a SHA-256 signature. While this sounds complicated, it's rather straightforward:

The salt is an 8- to 16-character random string. The demo app generates a 16-character hexadecimal string.
The timestamp is represented as Unix time, or "seconds since Jan 1, 1970, 00:00".
The signature is generated from a SHA-256 hash of these values:
- Salt and timestamp
- The HTTP method used (in lowercase)
- The complete request body
The hash—or rather, the hex digest of it—is then Base64 encoded.

This is what the complete signature() function looks like:

func signature(httpMethod string, urlPath string, salt string, timestamp string, accessKey string, secretKey string, body string) string {

    // create a sha256 HMAC with the secret key
    hash := hmac.New(sha256.New, []byte(secretKey))

    // sign the request
    hash.Write([]byte(strings.ToLower(httpMethod) + urlPath + salt + timestamp + accessKey + secretKey + body))

    // get the hex digest of the hash and base64-encode it
    hexdigest := make([]byte, hex.EncodedLen(hash.Size()))
    hex.Encode(hexdigest, hash.Sum(nil))
    return base64.StdEncoding.EncodeToString(hexdigest)
}

With this function, you can create a request() function that takes an HTTP method, a URL path representing the API endpoint, and a request body. It generates the signature, calls the API endpoint, and returns the response body or an error message.

The URL path must start with the API version number—for example, /v1/data/countries.

Please note: It's not recommended to use the default HTTP client from net/http if you want to set a request time-out. To avoid creating a new HTTP client every time request() is called, set up a RapydClient struct and make request() a method of that struct. Later, you will create a server struct that stores an instance of this client during its lifetime.

The following code is the request() function, along with the custom HTTP client:

type RapydClient struct {
    c *http.Client
}

func NewRapydClient() *RapydClient {
    return &RapydClient{
        c: &http.Client{
            Timeout: 10 * time.Second,
        },
    }
}

func (rc *RapydClient) request(method string, urlPath string, body []byte) ([]byte, error) {
    // turn the body into an io.Reader
    b := bytes.NewReader(body)

    // create a request with all headers required for authentication.
    req, err := http.NewRequest(method, "https://sandboxapi.rapyd.net"+urlPath, b)
    if err != nil {
        return nil, fmt.Errorf("Failed to create request: %v", err)
    }
    timestamp := fmt.Sprintf("%d", time.Now().Unix())
    salt := fmt.Sprintf("%016x", rand.Uint64())
    key := os.Getenv("RAPYD_ACCESS_KEY")
    secret := os.Getenv("RAPYD_SECRET_KEY")
    if key == "" || secret == "" {
        log.Fatalln("Please set the environment variables RAPYD_ACCESS_KEY and RAPYD_SECRET_KEY before starting the server.")
    }
    req.Header.Set("access_key", key)
    req.Header.Set("salt", salt)
    req.Header.Set("timestamp", timestamp)
    req.Header.Set("signature", signature(method, urlPath, salt, timestamp, key, secret, string(body)))

    // run the request and return the response body.
    resp, err := rc.c.Do(req)
    if err != nil {
        return nil, fmt.Errorf("Failed to send request: %v", err)
    }
    defer resp.Body.Close()
    respBody, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("Failed to read response body: %v", err)
    }
    return respBody, nil
}

Create the "Create Checkout Page" API Call

With the HTTP client set up, it's time to build the specific Create Checkout Page call.

The minimum information that the client needs to pass over includes the following:

The amount of the payment
The currency
The user's country
A redirect URL that is called when the user finishes the checkout
Another redirect URL that is called when the user cancels the checkout

You can collect this data in a struct:

type CheckoutPage struct {
    Amount              float64 `json:"amount"`
    Country             string  `json:"country"`
    Currency            string  `json:"currency"`
    CompleteCheckoutURL string  `json:"complete_checkout_url"`
    CancelCheckoutURL   string  `json:"cancel_checkout_url"`
}

Please note: The struct tags help translate the field names into JSON-compatible names.

As you can see, creating the checkout page is straightforward. You just fill the struct, marshal it into JSON format, call the Create Checkout Page API, and parse the response to get the redirect URL that starts the checkout flow at Rapyd's end. The Web server then redirects the browser to that URL.

The function that you'll create for these steps receives the selected number of items to set the total amount to pay. When running the app, try setting different item counts in the shopping cart and observe how the total amount on the checkout pages changes accordingly.

A note on the parsing of the API response: The Create Checkout Page call returns a large nested JSON structure with lots of useful info, but for this demo app, you need only the redirect URL (and the error information in case something goes wrong). This means you won't unmarshal the JSON into a Go struct. Instead, you'll unmarshal into maps and fetch the values from there.

func (s *Server) createCheckoutPage(host string, c int) (string, error) {

    // create the Rapyd checkout page with data from the basket.
    checkoutPage := CheckoutPage{
        Amount:              5.99 * float64(c),
        Country:             "US",
        Currency:            "USD",
        CompleteCheckoutURL: fmt.Sprintf("http://%s/complete", host),
        CancelCheckoutURL:   fmt.Sprintf("http://%s/cancel", host),
    }

    reqBody, err := json.Marshal(checkoutPage)
    if err != nil {
        return "", fmt.Errorf("error marshalling json: %w", err)
    }
    log.Println("createCheckoutPage payload:", string(reqBody))
    body, err := s.rapydClient.request("POST", "/v1/checkout", reqBody)
    if err != nil {
        return "", fmt.Errorf("error calling /v1/checkout: %w", err)
    }

    // parse the response dynamically and return the redirect URL
    var checkoutResponse map[string]any
    err = json.Unmarshal(body, &checkoutResponse)
    if err != nil {
        return "", fmt.Errorf("cannot unmarshal response from /v1/checkout: %w, body: %s", err, string(body))
    }
    status := checkoutResponse["status"].(map[string]any)
    if status["error_code"] != "" {
        return "", fmt.Errorf("error creating checkout page: %s: %s",
            status["status"],
            status["message"],
        )
    }

    data := checkoutResponse["data"].(map[string]any)
    return data["redirect_url"].(string), nil
}

Add HTML Pages and HTTP Handlers

Now that the checkout page is in place, the next step is to set up the structure of the user-facing pages. This app will serve three pages and a form handler:

The home page: This is also the simple shopping cart. It contains a form for selecting the number of pairs of socks to order.
A form handler: The shopping cart form calls this handler to deliver the cart to the checkout process. The form handler takes the cart data and calls the Create Checkout Page API to initiate the checkout process.
Two pages to which the checkout process returns: These are for when the user completes or cancels the checkout. These are the pages whose URLs you'll send to the Create Checkout Page API as redirect URLs.

To help keep the code short and simple, you don't need to use templates and can instead store the HTML for the pages in a map of plain static strings.

var (
    html map[string]string = map[string]string{
        "home": `<!doctype html>
<html lang='en'>
    <head>
        <meta charset='utf-8'>
        <title>Rapyd Checkout Demo</title>
    </head>
    <body>
        <header>
            <h1>Rapyd Checkout Demo</h1>
        </header>
        <main>
            <form action='/checkout' method='POST'>
                <div>
                    <h2>Buy woolen socks</h2>
                </div>
                <div>
                    <label>Number of items:</label>
                    <input type='text' name='count' value='1'>
                </div> 
                <input type='submit' value='Continue to checkout'> </div>
            </form>
        </main>
    </body>
</html>`,
        "complete": `<!doctype html>
<html lang='en'>
    <head>
        <meta charset='utf-8'>
        <title>Rapyd Checkout Demo</title>
    </head>
    <body>
        <header>
            <h1>Rapyd Checkout Demo</h1>
        </header>
        <nav>
            <a href='/'>Home</a>
        </nav>
        <main>
            <h2>Checkout complete</h2>
        </main>
    </body>
</html>`,
        "cancel": `<!doctype html>
<html lang='en'>
    <head>
        <meta charset='utf-8'>
        <title>Rapyd Checkout Demo</title>
    </head>
    <body>
        <header>
            <h1>Rapyd Checkout Demo</h1>
        </header>
        <nav>
            <a href='/'>Home</a>
        </nav>
        <main>
            <h2>Checkout canceled</h2>
        </main>
    </body>
</html>`,
    }
)

The home page handler displays the "home" element from the previous map.

Here, you use the standard router "ServeMux" from net/http. Due to the routing rules of ServeMux, the route "/" is a catch-all pattern if no other more specific routes match. The home page handler, therefore, needs to test for an exact match before serving the home page.

func (s Server) homeHandler(w http.ResponseWriter, r *http.Request) {
    if r.URL.Path != "/" {
        http.NotFound(w, r)
        return
    }

    w.Header().Set("Content-Type", "text/html")
    fmt.Fprint(w, html["home"])
}

The checkout handler receives the form contents through a POST call and triggers the checkout flow by creating the checkout page and redirecting the browser to it.

If a GET request comes in, then most likely, the user has hit the browser back button. In this case, the checkout handler silently redirects to the home page.

func (s Server) checkoutHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != "POST" {
        http.Redirect(w, r, "/", http.StatusFound)
        return
    }

    err := r.ParseForm()
    if err != nil {
        log.Println("Failed to parse form:", err)
        http.Error(w, "Internal Error", http.StatusInternalServerError)
        return
    }
    itemCount, err := strconv.Atoi(r.Form.Get("count"))
    if err != nil {
        log.Println("Failed to parse itemCount:", err)
        http.Error(w, "Invalid item count entered", http.StatusInternalServerError)
        return
    }

    rapydCheckoutPage, err := s.createCheckoutPage(r.Host, itemCount)
    if err != nil {
        log.Println("Cannot create checkout page:", err)
        http.Error(w, "Internal Server Error", http.StatusInternalServerError)
        return
    }
    http.Redirect(w, r, rapydCheckoutPage, http.StatusFound)
}

The handlers for the /complete and /cancel pages are trivial. They display a message and provide a link to the home page.

func (s Server) completeHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html")
    fmt.Fprint(w, html["complete"])
}

func (s Server) cancelHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/html")
    fmt.Fprint(w, html["cancel"])
}

Wire the Routes to the Handlers and Start the Server

After setting up the handlers, you'll create a Server struct that holds a pointer to a RapydClient instance. Then you add a startServer() function that sets up a new router (ServeMux), wires the handlers to their routes, and finally starts the HTTP server on port 8080. (You'll need to update this if this specific port is already occupied on your machine.)

Now the web app is ready to run.

type Server struct {
    rapydClient *RapydClient
}

func startServer() {
    s := Server{
        rapydClient: NewRapydClient(),
    }
    // set up the router & wire the handlers to their routes
    mux := http.NewServeMux()
    mux.HandleFunc("/", s.homeHandler)
    mux.HandleFunc("/checkout", s.checkoutHandler)
    mux.HandleFunc("/complete", s.completeHandler)
    mux.HandleFunc("/cancel", s.cancelHandler)

    // create and run the server.
    server := &http.Server{Addr: ":8080", Handler: mux}
    log.Println("Server running on localhost:8080")

    err := server.ListenAndServe() // this call blocks until an error occurs.
    log.Println("Server error:", err)

}

Complete the Code with a Main Function

With all of the above in place, the main function is a one-liner:

func main() {
    startServer()
}

And with that, you're almost done!

If you happen to use a pre-1.20 Go toolchain, you need to seed the random number generator. Otherwise, the salt is always the same when you restart the app. Security-wise, this is not recommended, and the Rapyd API rightfully complains when it receives the same salt value twice. If you use Go 1.20 or later, you don't need this seed call.

func init() {
    rand.Seed(time.Now().UnixNano())
}

Test the Final App

You're almost done. Now it's time to start the server and make it accessible to callbacks from Rapyd.

Run the Code

If the two environment variables are set, you can run the code right away or use the repo that contains the code in the go directory.

To run the server, cd into the source code directory and call the following:

go run .

Make the Server Accessible for Callbacks

At the end of the checkout flow, the Rapyd API service redirects the browser back to your web-shop server, which means the URLs that you pass to the API for that purpose cannot be localhost URLs because the web-shop server needs to be reachable on the internet.

You can run the demo app on a (ephemeral) server, or you can use a proxy service like ngrok, which will generate a random web address for you and redirect all traffic to a specified port on your local machine.

In addition, remote development environments like Gitpod.io usually provide a similar service to expose local ports through a generated proxy URL. For more info, check out the documents for your remote dev environment provider.

Go through the Checkout Flow

To complete the checkout flow, open the public URL of the web shop in your browser. You should see a shopping cart page prefilled with your dream socks.

Enter the number of pairs of socks that you want to buy, and click Checkout. Then the hosted checkout page will open.

Select a payment method, fill out the required fields, and click Place Your Order.

At this point, a Thank You page should open and list out any steps required to complete the payment. These steps depend on the payment method chosen.

Once you've followed the prompts, click Finish.

The flow redirects you back to the web shop, where the Checkout complete page opens.

If you click the back arrow on the payment page instead of following through the checkout, you will see the Checkout canceled page instead.

Congrats! You completed your first Rapyd checkout flow.

Conclusion

In this tutorial, you created a basic checkout flow where most of the code is standard Go web app code—and this is only the start! Rapyd is so much more than a checkout solution. Rapyd provides a suite of payment and financial services for businesses through a fast and easy-to-use platform, including cross-border transactions, digital wallets, and payment processing.

Check out the Rapyd API now and bring your online business to the next level.

Have any thoughts about this tutorial? We'd love to hear them! Post any thoughts or related questions in the Rapyd Developer Community.

Rapyd's React Summit Success: Engaging Developers in the Fintech Revolution

Kyle Pollock — Thu, 22 Jun 2023 12:49:06 +0000

In early June, Rapyd gathered with the React Summit in Amsterdam, leaving a memorable impression on the vibrant developer community. React Summit is an annual conference that covers anything related to React JS, gathering thousands of Full-stack and Front-end engineers from around the world.

The React Summit drew an impressive crowd of 1600 attendees from across Europe, providing opportunities to engage with some of the finest minds in the industry. Attendees filled the rooms and visited vendors to learn more, and connect over common goals. Rapyd offered attendees exclusive swag such as branded socks and coffee cups in exchange for creating a Client Portal account. Rapyd also offered an opportunity to participate in a coding challenge, which involved creating a checkout page using Rapyd's API. Participants had a chance to win an extraordinary trip to Rapyd's cutting-edge R&D centers in Tel Aviv or Dubai.

The Power of a Lightning Talk: Insights by Tiki

During the event Tiki Lobel, R&D Engineering Team Lead at Rapyd, took the stage for a powerful seven-minute lightning talk, titled "How to Become a Fintech Developer in Seven Minutes." This insightful session captured the attention of the audience, teaching them how to get started with integrating fintech solutions into applications. Tiki shared about the meaning and reach of fintech that is a part of nearly every global service and industry. She showed a couple Rapyd use cases and examples of what it looks like to generate the Hosted Checkout page for a payment with the Rapyd API.

Rapyd Solutions for Money Movement

If you visited the Rapyd exhibit, you’d find how team members were ready to showcase their product with a 10-minute demo, and discuss forward-thinking solutions. Rapyd developers were on standby to coach others through the process of getting started, and taking a stab at the Rapyd challenges. More developers dropped by the exhibit after Tiki's lightning talk further peaked interest from companies within the payments industry. The speed and ease of Rapyd’s integration resonated with developers, with some expressing that our solution surpassed their current experiences with other companies. Many small business owners were captivated by the breadth of Rapyd's product offerings, seeking further information on system stability and pricing.

Conclusions and Feedback: Connecting with the Developer Community

Developers learned from each keynote delivery, and developed meaningful connections with other attendees. Rapyd is always looking to engage in conferences, meetups, and with the largest developer communities around the world. After educating others and gathering feedback received from attendees, Rapyd will continue to provide better experiences for developers.