TG: 001
Title: Implementation guide for payment providers
Author: Mike Gaertner <[email protected]>, Owen Jacob <[email protected]>
Status: Active
Created: 2019-08-25
Updated: 2020-03-10
Version 2.0.0
This document describes the account setup and API implementation required to be completed by payment providers who wish to integrate with SSN.
This is a one time process although payment providers may wish to complete it programmatically so that the setup can be stored in version control for future reference. The following documents provide information on correctly setting up SSN accounts:
These endpoints can be used to determine the status of the payment provider's SSN API. The endpoint designs are documented here: status and info.
One time payments are where the payment provider prompts the user for payment authorization for each transaction.
The endpoint design is documented here.
Source code examples:
The payment provider should prepare the request to the payment address resolver as documented here. The resolver response will provide the payment provider with information to complete the transaction. There are several possible responses that should inform the payment provider's next step before completing the payment:
If the payment array:
- Contains only a single object with just an asset_code present -> the payment provider should prompt the user for an amount in that currency.
- Contains multiple objects with just asset_codes present -> the payment provider should prompt the user for an amount and the currency they wish to pay in.
- Contains only a single object with an asset_code and an amount present -> the payment provider should prompt the user to confirm the payment amount and currency.
- Contains multiple objects with asset_codes and amounts present -> the payment provider should prompt the user to confirm the payment amount and choose which currency they wish to pay in.
The payment provider should take the full request URL, sha256 hash the url and encode the result in hex to compare to the request hash (examples here). The SSN API can then be used to verify the signature using the endpoint documented here. A HTTP 200 response indicates the signature is valid. The request public key should match the payment receiving account of the merchant or a signer on this account.
The resolver for the payment address should already have checked a trustline was in place but the payment provider can ensure this by also checking the trustline using the endpoint here.
The payment provider's usual payment authorization options can be used here. Once the user has authorized the payment the payment provider should move the funds from the users account to an escrow account that holds SSN funds at the payment provider.
Using the information from the resolved payment address along with the users input the payment provider can use the endpoint documented here to build a payment transaction for SSN. The transaction should be signed by the payment provider key(s) and then submitted to the endpoint here. The response of the transaction endpoint will include the network ledger number and the network transaction hash provided the transaction was sucessfully accepted.
If a redirect URL was provided in the original request the payment provider should redirect to that URL with the transaction hash otherwise the payment provider can show the user a success screen along with the hash for the users records.
Pre-authorized payments are where the payment provider prompts the user for authorization once and then a merchant is able to pull transactions. The payment provider can optionally prompt the user for transaction limits.
The endpoint design is documented here.
Source code examples:
The payment provider should take the full request URL, sha256 hash the url and encode the result in hex to compare to the request hash (examples here). The SSN API can then be used to verify the signature using the endpoint documented here. A HTTP 200 response indicates the signature is valid. The request public key should match the public_key path parameter in the request.
The payment provider should check which currencies pre-authorization can be provided for the merchant.
The payment provider's usual authorization options can be used here. The payment provider could also provide the user with options to limit payments that use pre-authorization, for example: payment frequency limits or payment amount limits.
The user and merchant keys should be stored in a database table that is associated with the user along with the currencies authorized.
If a redirect URL was provided in the original request the payment provider should redirect to that URL with the user public key and an array of currencies accepted otherwise the payment provider can show the user a success screen.
The endpoint design is documented here.
Source code examples:
The payment provider should prepare the request to the payment address resolver as documented here. The resolver response will provide the payment provider with all of the information required to complete the transaction: The response must only contain only a single payment object with an asset_code and an amount present. The network address should be checked to verify if it is a subaccount in which case the trust account should be used in step 4 to find the existing pre-authorization, otherwise the network address should be used.
The payment provider should take the full request URL, sha256 hash the url and encode the result in hex to compare to the request hash (examples here). The SSN API can then be used to verify the signature using the endpoint documented here. A HTTP 200 response indicates the signature is valid. The request public key should be used in step 4 to find the existing pre-authorization.
The payment provider should check there is a trustline in place for the asset code and the network address.
The request public key should be matched to the user key and the network address should be matched to the merchant key in the payment providers pre-authorization database table. If the authorization exists the payment provider should move the funds from the users account to an escrow account that holds SSN funds at the payment provider.
Using the information from the resolved payment address the payment provider can use the endpoint documented here to build a payment transaction for SSN. The transaction should be signed by the payment provider key(s) and then submitted to the endpoint here. The response of the transaction endpoint will include the network ledger number and the network transaction hash provided the transaction was sucessfully accepted.
The endpoint design is documented here.
Source code examples: