Extend Embedded Components with the Temporary Token Flow

If you need more flexibility than Payabli’s low-code embedded components provide, you can use a workflow that gives you the best of both worlds: the security and ease of embedded components and the flexibility of direct-access APIs. This temporary token flow lets you use the EmbeddedMethod UI and PayMethod UI embedded components to create a temporary payment token. Then you use that token for further actions like creating a permanent token or processing a payment.

Using this approach, you can have more control over the transaction request. You can pass additional transaction parameters that can’t be passed through the EmbeddedMethod configuration without expanding your PCI scope. This approach also provides flexibility for you to implement solutions for different use cases, like:

Allowing the customer to choose whether to save the payment method permanently or not by presenting a checkbox in your UI.
Displaying payment status or results to the customer after processing the payment via API.
Handling errors that occur during the API calls.
Using split funding functionality.
Incorporating idempotency and timeout handling.

This workflow has two main steps:

Generate a temporary payment token

Use a component to generate a one-time use payment token.

Use the temporary token

Use the payment token in a request to make the token permanent or process a transaction (or both).

Generate a temporary token

The first step is to use the PayMethod UI or EmbeddedMethod UI embedded component to create a temporary token.

Choose a component based on the experience you prefer: the PayMethod UI opens in a modal, and the EmbeddedMethod UI displays inline on the page.

Whichever component you choose must be configured to create a temporary payment token, by setting temporaryToken to true.

For full configuration options and examples, see EmbeddedMethod UI Configuration Reference and PayMethod UI Configuration Reference.

When used, the component returns the temporary payment token in the response as referenceId. For example:

Example response
  response.responseText: 
  "Success"

  response.responseData
  {"referenceId":"30e7658e-5c2c-4638-8308-b48edec0718b-1647","resultCode":1,"resultText":"Added","customerId":1647}

The response looks the same when saving a payment method with either component.

Use the temporary token

After you get the temporary token from the component, you have different options for using it. You can convert it to a permanent token, process a payment, or process a payment and save the token.

The payment token is passed as tokenId only in requests to the TokenStorage endpoints. If you are using a payment token to make a transaction with a MoneyIn endpoint, it’s passed as storedMethodId. Pay close attention when working with these code examples.

Option 1: Create a permanent token

To convert the temporary token returned by the component to a permanent one, make a request to the TokenStorage/Add endpoint, passing the temporary token with tokenId.

Convert a temporary token to permanent
  curl --request POST \
      --url https://api-sandbox.payabli.com/api/TokenStorage/add?temporary=false \
      --header 'accept: application/json' \
      --header 'content-type: application/*+json' \
      --header 'requestToken: <API TOKEN>' \
      --header 'idempotencyKey: 6B29FC40-CA47-1067-B31D-00DD010662DA' \
      --data '
  {
    "paymentMethod": {
      "method": "card",
      "tokenId": "c9700e93-b2ed-4b75-b1e4-ca4fb04fbe45-224" 
  },
    "customerData": {
      "customerId": 0,
      "firstName": "John",
      "lastName": "Doe",
      "company": "Sunshine LLC",
      "customerNumber": "3456-7645A",
      "billingAddress1": "123 Main Street",
      "billingCity": "Johnson City",
      "billingState": "TN",
      "billingZip": "37612",
    },
    "entryPoint": "mypaypoint",
    "source": "web",
    "methodDescription": "Main card"
  }
  '

A successful request returns a 200 response with a JSON body. The value in “ReferenceId” is both the storedMethodId for transactions, and the methodId for managing the payment method.

Success response example
{
  "isSuccess": true,
  "responseText": "Success",
  "responseData": {
    "ReferenceId": "32-8877drt65345632-678",
    "ResultCode": 1,
    "ResultText": "Approved",
    "CustomerId": 0
  }
}

Option 2: Process a payment

To process a one-time payment, call MoneyIn/GetPaid endpoint and pass the temporary token as storedMethodId along with other parameters, such as OrderID and idempotencyKey. Make a payment with a saved payment method

Make a payment with a saved payment method
curl --request POST \
  --url https://api-sandbox.payabli.com/api/MoneyIn/getpaid \
  --header 'Content-Type: application/json' \
  --header 'idempotencyKey: bf21c30673244141b39d81d73a42613d' \
  --header 'requestToken: <api-key>' \
  --data '{
    "paymentMethod": {
      "method": "card",
      "storedMethodId": "f4ee4209bbc347248dbc97ab09f17820"
    },
    "orderId": "1009-WEB",
    "entryPoint": "47a9s3e200o",
    "paymentDetails": {
      "totalAmount": 129.35,
      "serviceFee": 0
    },
    "customerData": {
      "customerId": 253,
      "firstName": "Rachel",
      "lastName": "Borodino",
      "customerNumber": "12345679"
    }
  }'

This is just like processing a transaction with any other payment method. See Make a Sale Transaction for more information and example requests and responses.

Option 3: Process a payment and create a permanent token

Use the saveIfSuccess parameter when calling MoneyIn/GetPaid, to process a payment and generate a permanent payment method token in a single API call.

Process a payment and create a permanent token
  curl --request POST \
    --url https://api-sandbox.payabli.com/api/MoneyIn/getpaid \
    --header 'Content-Type: application/json' \
    --header 'idempotencyKey: bf21c30673244141b39d81d73a42613d' \
    --header 'requestToken: <api-key>' \
    --data '{
    "paymentMethod": {
      "method": "card",
      "storedMethodId": "728e2ba3-5526-4fe6-ac14-59c438beb436-0",
      "saveIfSuccess": true
    },
    "orderId": "1009-WEB",
    "entryPoint": "47a9s3e200o",
    "paymentDetails": {
      "totalAmount": 129.35,
      "serviceFee": 0
    },
    "customerData": {
      "customerId": 253,
      "firstName": "Rachel",
      "lastName": "Borodino",
      "customerNumber": "12345679"
    }
  }'

You should expect to see a response like the following:

  {
  "responseText": "Success",
  "isSuccess": true,
  "pageIdentifier": null,
  "responseData": {
    "authCode": "123456",
    "referenceId": "227-d30f8a47ddaf4fa989016d21d08000abd",
    "resultCode": 1,
    "resultText": "Approved",
    "avsResponseText": "No address or ZIP match only",
    "cvvResponseText": "CVV2/CVC2 no match",
    "customerId": 1409,
    "methodReferenceId": "1ed73dfa-3c67-4076-8f8c-9f26317993ed"
  }
}

The transaction’s ID is returned as referenceId, and the saved payment method ID is methodReferenceId.

Pay In

Pay Out

Pay Ops

Extend Embedded Components with the Temporary Token Flow

Generate a temporary token

Use the temporary token

Option 1: Create a permanent token

Option 2: Process a payment

Option 3: Process a payment and create a permanent token

See Also:

Pay In

Pay Out

Pay Ops

​Generate a temporary token

​Use the temporary token

​Option 1: Create a permanent token

​Option 2: Process a payment

​Option 3: Process a payment and create a permanent token

See Also:

Generate a temporary token

Use the temporary token

Option 1: Create a permanent token

Option 2: Process a payment

Option 3: Process a payment and create a permanent token