Step-by-step instructions

Follow these for a seamless integration with Pay1st!

Preface

Before starting with the Pay1st implementation, our team will set you up with a provider account in the Pay1st Admin Console, the back-end infrastructure of Pay1st that allows you to track all orders, adjust products and bundles, access customized analytics and more.

Pay1st Admin Console Integration Steps

  1. Your admins will be granted access to the Pay1st Admin Console to your shared emails after the request is approved by Pay1st.
  2. You will receive a welcome email. Follow the steps in the email to get access to the Pay1st admin console.
  3. Pay1st admin will help you to create products and product bundles under the product inside the Pay1st console which is corresponding to game merchandise that the provider will have in their product portfolio.
  4. The product created at the Pay1st admin console has to be updated to populate a few important configurations as below:
    1. Summary Webhook: Implementation to be provided by the provider and to be consumed by Pay1st. Details about this are mentioned in the next integration steps.
    2. User Info Webhook: Implementation to be provided by the provider and to be consumed by Pay1st. Details about this are mentioned in the next integration steps.
    3. Transaction Success Callback URL: For successfully completed transactions, this URL is called if automatic redirect is enabled.
    4. Transaction Failure Callback URL: When the transaction is failed, this URL is called if automatic redirect is enabled.
    5. The summary and user info webhooks should be protected by basic authorization and their details should be mentioned in 'Basic Auth Username' and 'Basic Auth Password' fields as shown below. The Pay1st API server will use this credential data to make these webhook calls.
Product configuration in the Pay1st console

Product configuration in the Pay1st console

  1. Create product bundle under newly created product.
    1. In the edit screen of the product bundle, populate the 'External ID' value with the provider's own bundle id or price point.
  2. Create a new product Fulfilment method
    1. With the help of Pay1st Admin create product fulfillment methods for each newly added product.
  3. Associate payment method to product
    1. With the help of Pay1st Admin associate payment method to the product.

Client-Side Implementation Steps

  1. Initialise Payment

    • Get Product Bundle Ids from the Pay1st Admin Console. These are for the bundles created for each purchase bundle that is created.
    • Set up a success callback URL for the product from the Pay1st Admin Console. This will be called when a payment is successful as mentioned in section here.
    • Set up a failure callback URL for the product from Pay1st Admin Console. This will be called when a payment has failed as mentioned in section here.
    • When a user selects a bundle, redirect to the platform purchase endpoint with the following params:
    ParamFormatDescription
    usernameStringThe user identity. This should be a unique identifier used to identify the user in the game.
    platformString {AND, IOS, WEB}The mobile platform is used to load the Platform. Use WEB for payments from web applications.
    productBundleIdLongThe bundle identifier as configured in Pay1st console
    productBundleExternalIdStringThe bundle identifier for the Provider
    countryCodeStringThe ISO 2 country code, e.g. ZA
    externalReferenceString (Optional)Your own reference that you would want to use for reconciliation. It will be sent back in the summary webhook.
    amountDecimal (Optional)The amount to pay.
    currencyCodeString (Optional)The currency code for the amount.
    partnerSourceStringThe source identifying the partner.
    languageString (Optional)The language to render for localisation. (Supported values: en, ar, fr)

    URL params:

    https://<payments_url>/payment?username=<USERNAME>&platform=<PLATFORM>&productBundleId=<PRODUCT_BUNDLE_CODE>&countryCode=<COUNTRY_CODE>&exernalReference=<EXTERNAL_REFERENCE>

  2. Different client-Side implementations are as below:

    1. Web client integration guide is available here
    2. Android/iOS client integration guide is available here
    3. Unity client integration guide is available here

Payments – Server-Side Integration Steps

  1. User Info Webhook
    1. The Pay1st backend API server needs to validate the user trying to buy game merchandise on the Pay1st console.
    2. The provider needs to provide this API implementation so that Pay1st can validate the user.
    3. Detailed documentation on how to implement user info webhook is available here
  2. Summary Webhook
    1. For fulfillment of providers’ game merchandise, Pay1st needs to call the providers’ fulfillment API, so that the game merchandise can be delivered to the user.
    2. The provider needs to provide this API.
    3. Detailed documentation on how to implement summary webhook is available here
  3. Query Payment Status
    1. The provider needs to make sure that the user has made a successful payment on the Pay1st console.
    2. The provider can know the status of the payment by calling Pay1st API to query payment status.
    3. Detailed documentation on how to implement querying payment status API is available here

Payouts – Server-Side Integration Steps

  1. The detailed payout integration guide is available here