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 look at 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 Status 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 Postman.
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.