Link to web payment on iOS - US 🇺🇸

iOS in the US permits the use of standard "naked" hyperlinks without requiring integration with Apple's StoreKit APIs for external linkouts. Thus, launching Coda Links in iOS is a highly streamlined process.

Below is the step-by-step guide for linking US users to from an iOS App to your Coda-hosted Payment Page:

Prerequisites

Ensure that you have followed the steps in Set up payments, and obtained a API Key that can be used with our Codapay APIs.

This is the standard integration that allows you to call Codapay's Payment Init API, which returns a unique web checkout URL.

Step 1: Get a Payment Link from Coda's Payment API

A summary of the Payment Init API specs are as follows:

For the full list of supported request & response parameters, refer to Initiate a payment request

Environment

Endpoint URL | Method: POST

Sandbox

https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/init.json

Production

https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment/init.json

{
    "initRequest": {
        "country": 158,
        "payType": 82,
        "apiKey": "live_****************************",  //Obtained from Coda Portal
        "projectId": 21                                 //Obtained from Coda Portal
        "orderId": "12321312321314",                    //Your internal order identifier
        "currency": 901,
        "items": [
            {
                "code": "1",
                "name": "Test Item",
                "price": 3.99
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}

{
    "initResult": {
        "resultCode": 0,
        "txnId": 7714940366302672840,
        "redirectUrl": "https://airtime.codapayments.com/airtime/begin?txn_id=7144594637002072212&browser_type=mobile-web&utm_source=facebook”
    }
}

{
    "initResult": {
        "resultCode": 103,
        "resultDesc": "This transaction has been cancelled. No charges were made. (error:103)",
        "txnId": 0
    }
}

2. Launch the URL: Simply invoke standard iOS networking methods to launch the URL in an external browser.

For optimal functionality, open the URL in an external browser rather than an in-app webview, as certain e-wallet payment features may be limited in webviews.

SwiftUI Sample

import SwiftUI

struct ContentView: View {
    @Environment(\.openURL) var openURL

    var body: some View {
        Button("Visit Apple") {
            if let url = URL(string: "https://www.apple.com") {
                openURL(url) // Opens in the default external browser (usually Safari)
            }
        }
    }
}

UIKit Sample

import UIKit

if let url = URL(string: "https://www.apple.com") {
    UIApplication.shared.open(url, options: [:], completionHandler: nil)
}

Step 2: Receive a payment success notification from Coda

Coda will send a notification to your Complete Notification URL (configured on Coda Portal during Set up payments). This notification is sent to you when the user has successfully completed their payment on Coda-hosted Payment Page.

// Sample for non-USD payment
https://<your_webhook_url>?
  TxnId=7715121708032676249
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.00
  PaymentType=237
  ResultCode=0
  Checksum=6b6c5e0f835f9f1442726bed3aedc3c9
  PayTaxRate=8.00 
  PayCurrency=MYR 
  PayAmount=1.00 
  OriginAmount=1.00 
  OriginCurrency=MYR 
  SubTotalPrice=0.93

// Sample for USD payment, converted to local currency
https://<your_complete_notification_url>?
  TxnId=7715122576202672831
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.17
  PaymentType=237
  ResultCode=0
  Checksum=10741fa6be7e6f2b189f029b3f8a0963
+ USDPrice=0.30
  PayTaxRate=8.00
  PayCurrency=MYR
  PayAmount=1.17
  OriginAmount=0.30
  OriginCurrency=USD
  SubTotalPrice=1.08

You need to respond to the notification from Coda with an acknowledgement, to confirm that it has been successfully received.
1. If your application processes the notification successfully, respond with ResultCode=0
2. Otherwise, return an error code.

If no response is received, the notification will be re-sent 3 times at 5-minute intervals. If all attempts fail, an email alert will be triggered. To subscribe to this email alert notifications, go to the Coda Portal > Team > Manage Access > Tick "Transaction Notification" > Save Changes

Step 3: Double check the transaction status with Payment Result Inquiry API (Recommended)

We highly recommend that you call the InquiryPaymentResult API after receiving the notification, to confirm the status of the payment once more. This will help reconcile the transaction status between your system and Coda's before releasing the purchased item to the user. The details are as follows:

Environment

Endpoint URL | Method: POST

Sandbox

https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/inquiryPaymentResult.json

Production

https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment//inquiryPaymentResult.json

{    
    "inquiryPaymentRequest":
    {
        "apiKey": "live_****************************",
        "country": 702 //This field is only needed for v2.0 API
        "projectId": 21 //This field is only needed for v2.0 API
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}

// Sample for non-USD payment
{
    "paymentResult": {
        "orderId": "365f5Z619951c1a4b8",
        "originAmount": 1,
        "originCurrency": "MYR", 
        "payAmount": 1, 
        "payCurrency": "MYR", 
        "payTaxRate": 8, 
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 237
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "channelId",
                    "value": 237
                },
                {
                    "key": "status",
                    "value": "success"
                }
            ]
        },
        "resultCode": 0,
        "resultDesc": "Success",
        "subTotalPrice": 0.93, 
        "totalPrice": 1, // Always the same as payAmount
        "txnId": 7715121708032676249
    }
}

// Sample for USD payment, converted to local currency
{
    "paymentResult": {
        "orderId": "365f5Z619951c1a4b8",
        "originAmount": 0.3, 
        "originCurrency": "USD", 
        "payAmount": 1.17, 
        "payCurrency": "MYR", 
        "payTaxRate": 8, 
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 237
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "channelId",
                    "value": 237
                },
                {
                    "key": "status",
                    "value": "success"
                }
            ]
        },
        "resultCode": 0,
        "subTotalPrice": 1.08,
        "totalPrice": 1.17, // Always the same as payAmount
        "txnId": 7715122576202672831
    }
}

For the full list of supported request & response parameters, refer to Check a transaction status

Step 4: Post-Purchase UX & Deep Linking

Item Fulfillment: When the payment succeeds, Coda Webstore completes the payment and automatically sends a server-to-server item fulfillment request to your backend. This should already be covered in the Webstore basic setup. No changes required here
User can click to go back to App via deep link: To ensure this redirection happens smoothly, you must provide Coda with a deep link that can redirect users back to your iOS app upon a successful purchase.
1. This link can be configured in Coda Portal under Complete Landing Page URL. If you have already configured this during Set up payments, no change is required.
2. Once the user is deep-linked back to your app, they should seamlessly receive their items. In addition, your app can display a purchase success screen with confetti animations!

Refer to Redirecting users from Coda Links back to your appto learn how to setup back-to-app redirection correctly for your iOS App.

User can explore Webstore's offers & LiveOps campaigns
- If you have a Coda Webstore published, the post-purchase screen will display your best Webstore offers to the user automatically, encouraging them to explore & become a loyal direct-to-webstore customer.
- Find out how here: How to enable LiveOps on post-purchase screen

Why having LiveOps features on Coda Links is crucial for your long-term revenue

Linkouts are not free: Including in the US, Google and Apple are fighting tooth and nail to impose fees on external purchases to protect their revenue streams. For instance, Google charges up to a 20% commission on purchases made within 24 hours of a user following an external payment link. Similarly, Apple imposes a 15% commission on website sales initiated within 7 days of an end user tapping an out-of-app link. If users stick exclusively to linkout payments directly from the app, publisher margins will continuously be undercut by these fees with no way out.
Webstore loyalty builds long-term profitability: Converting purchasers from in-app to webstore should be the ultimate goal. Publishers can use elements on the linkout success page to convert users into direct webstore customers, which makes the long-term cost per transaction significantly lower. When users build a habit of going directly to out-of-app channels like a webstore, they bypass the in-app link altogether. These direct visits make their future purchases completely out-of-reach for the app platforms, meaning all fee savings go straight to the publisher's bottom line.

PreviousLink users out to Coda-hosted Payment Page

NextLink to web payment on Android - US 🇺🇸

Last updated 5 months ago

Was this helpful?