External Payment Platforms
There may be cases where you need to collect user payments on an external payment platform, and use those funds to perform a Tilia transaction. For example, you may want to collect payments on the platform where your game is distributed, then use those funds in issuing virtual tokens managed by Tilia.
Tilia has two special features to enable these cases:
- Facilitator wallet: A special USD wallet that can be used to pay for a Tilia invoice on behalf of your user. Facilitator wallets are prefunded by you for this purpose.
- "Pay on Behalf of" (POBO) payment method: A special payment method representing the user's account on the external payment platform. Unlike traditional payment methods (e.g. credit cards), payments made using the POBO payment method are deducted from your Facilitator wallet.
When the user purchases a product through the external payment platform, you will create a corresponding Tilia invoice, specifying the user's POBO payment method. When the invoice is executed, the funds will be deducted from your Facilitator wallet.
attention
You are responsible for confirming that such usage does not violate the terms of any agreement you have with the external payment platform.
Things to note
- If your Faciliator wallet doesn't contain sufficient funds, the transaction will fail.
- Each user can have multiple POBO payment methods. The user's transaction history will specify the external platform associated with the payment method used.
- You need to construct your invoices such that any fees charged, including those imposed by the external platform, are clearly communicated to the end user.
- POBO payment methods can be added after the initial user registration, through the Update Account API call.
- This system currently supports Steam, Oculus, Apple Pay, and Google Pay. If you'd like to see more systems supported, please feel free to ask.
Purchase using POBO Payment Method
This example explains how to create a purchase transaction using a user's POBO payment method.
Prerequisites
To complete this example, you'll need the following:
-
An Access Token with the requisite scopes:
read_payment_methods,write_invoices - The Tilia account ID for the purchasing user. This account must be associated with the user's ID on the external platform where you are accepting payment. For example, if you are accepting the user's payment on Steam, you will need to add the user's Steam ID to the user's Tilia account profile. This association is what creates a POBO payment method for the user. Refer to the Accounts API Reference for information on creating and updating user accounts.
- Funds in your Facilitator wallet. Please contact Tilia for more information on funding this wallet.
The process of creating a transaction involves the following steps:
Step 1: Retrieve the POBO payment method
Step 2: Create and pay the invoice
Step 1: Retrieve the POBO payment method
Retrieving payment methods requires an API token with the scope read_payment_methods.
To check for available methods, submit a GET request with the account_id to the /transaction-methods endpoint.
curl --location --request GET https://payments.staging.tilia-inc.com/transaction-methods/{account_id} \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \The response JSON returns the available transaction methods for the specified account. You can use the payment method ID that corresponds to the external platform through which payment was collected. For example, if the buyer paid via Steam, use the payment method ID for the Steam wallet.
{
"status": "Success",
"message": [],
"codes": [],
"payload": {
"account_id": "7ebf3cfa-426b-42ac-9d03-d738cc650889",
"balances": {
"account_id": "7ebf3cfa-426b-42ac-9d03-d738cc650889",
"balances": {
"USD": {
"spendable_balance": {
"balance": 0,
"display": "$0.00"
},
"spendable": null,
"convertible": null
}
}
},
"capabilities": {
"deposit": [],
"payout": [],
"purchase": [
"25dad3e1-4163-436c-9ee4-9011fd9a829c",
"ab24605c-318f-48ff-ade7-83896a770c8f",
"91381a9c-04e7-4833-92e8-d38ed2941cb1"
]
},
"payment_methods": {
"25dad3e1-4163-436c-9ee4-9011fd9a829c": {
"id": "25dad3e1-4163-436c-9ee4-9011fd9a829c",
"account_id": "7ebf3cfa-426b-42ac-9d03-d738cc650889",
"method_class": "oculus",
"display_string": "Oculus Wallet",
"provider": "pobo",
"psp_reference": "78623e55-0077-49c9-a8c0-430b28994026",
"psp_hash_code": "<oculus_id>",
"processing_currency": "USD",
"pm_state": "ACTIVE",
"integrator": "acme",
"created": "2022-03-04 17:36:02",
"updated": "2022-03-04 17:36:02",
"tags": [],
"payment_method_id": "25dad3e1-4163-436c-9ee4-9011fd9a829c"
},
"91381a9c-04e7-4833-92e8-d38ed2941cb1": {
"id": "91381a9c-04e7-4833-92e8-d38ed2941cb1",
"account_id": "7ebf3cfa-426b-42ac-9d03-d738cc650889",
"method_class": "registration",
"display_string": "Default USD Wallet",
"provider": "wallet",
"psp_reference": "4d85a6be-37b1-4e98-a308-add9346e77c0",
"psp_hash_code": "",
"processing_currency": "USD",
"pm_state": "ACTIVE",
"integrator": "acme",
"created": "2022-03-04 17:31:50",
"updated": "2022-03-04 17:31:50",
"tags": [],
"wallet_balance": "0",
"payment_method_id": "",
"provider_data": {
"wallet_id": "4d85a6be-37b1-4e98-a308-add9346e77c0",
"wallet_balance": "0",
"balance": 0
}
},
"ab24605c-318f-48ff-ade7-83896a770c8f": {
"id": "ab24605c-318f-48ff-ade7-83896a770c8f",
"account_id": "7ebf3cfa-426b-42ac-9d03-d738cc650889",
"method_class": "steam",
"display_string": "Steam Wallet",
"provider": "pobo",
"psp_reference": "b3ef0844-800f-4fc5-93b5-abbec305f4a3",
"psp_hash_code": "<steam_id>",
"processing_currency": "USD",
"pm_state": "ACTIVE",
"integrator": "acme",
"created": "2022-03-04 17:36:02",
"updated": "2022-03-04 17:36:02",
"tags": [],
"payment_method_id": "ab24605c-318f-48ff-ade7-83896a770c8f"
}
}
}
}Step 2: Create and pay the invoice
You can use the POBO payment method in any of the purchase transactions supported by Tilia. Refer to the Processing Transactions section of this guide for more information.