Skip to main content

How to charge payment details

Learn how to send payment details to a payment provider using a token​

Overview​

Piiano Vault enables you to charge a customer with one call without exposing the payment details you collected online. This feature is useful when you want to charge a customer's payment details in a PCI-compliant way.

This tutorial uses a sandbox environment in the managed version of Vault to show you how to securely charge a customer's payment details by calling a payment gateway with a payment details token. The process is essentially the same for the managed version of Vault.

What you learn​

  • How to create a Piiano Vault API key to communicate with Piiano Vault from your server code.
  • How to authorize a payment gateway API to be used by Piiano Vault.
  • How to charge payment details through a payment gateway with the Piiano Vault REST API using a Vault global identifier that references those details.

Prerequisites​

To charge a payment method, you should first save the payment details in your Vault and obtain the Vault global identifier for those details. How to do that is covered in the collect payment details how to.

Step 1: Create a Piiano Vault API key​

A Piiano Vault API key is a unique identifier that enables you to execute data operations in Piiano Vault. This tutorial uses the key to invoke a payment gateway API with a payment details token to start payment processing. In line with the principle of least privilege, this key is associated with a user who has just enough capability to process payments.

To create a key:

  1. Log in to your Piiano Vault account. You can sign up for a free sandbox environment if you don't have a Piiano Vault account.
  2. Navigate to your Vault dashboard.
  3. Open Identity and Access from the left navigation.
  4. On the Roles tab, select New role.
  5. Name the role PaymentGatewayProcessor, and choose the CapActionsInvoker capability and PolAllowInvokeHTTPCallAction policy.
  6. Select Create role.
  7. On the Users tab, select New user.
  8. Give the user a name (e.g., PaymentGatewayProcessor) and choose the PaymentGatewayProcessor role. Make sure the user state is set to Enabled.
  9. Select Create user.
  10. For the PaymentGatewayProcessor user, click the actions dropdown and select Regenerate API key. This generates a new API key for the user. You can use this API key in your server code to invoke the payment gateway API with a template to start payment processing.

Step 2: Authorize payment gateway endpoint​

In the managed version of Vault, Piiano must validate that your payment gateways are PCI-compliant for regulatory reasons. Therefore, you can only send credit card information to payment gateways after Piiano approves and configures them in your vault.

For the sandbox environment, you send us the domain of a testing system you want to receive the simulated payment processing. Using a standard testing platform, such as pipe dream, is recommended.

Contact us to authorize a payment gateway API for use in your production managed-Piiano Vault.

Step 3: Charge payment details​

After authorizing the payment gateways, you call the payment gateway API from Vault using the Piiano Vault invoke HTTP call action operation. This operation takes a request body that consists of:

  1. template_variables that defines a variable used in the request to identify the payment details source. In this case, the Vault global identifier pvlt:detokenize:payment_details::bb5e17ce-38b1-4b3f-9b4b-40801f9672d1 which tells the operation it gets data from a payment_details collection token.
  2. request that defines the call to the payment gateway API. This object includes references to the data that needs to be sent to the API using the template variable and collection property. For example, .payment_details.number to reference the credit card number.

The HTTP call action replaces the template content with the payment details before invoking the payment gateway API. This process ensures that the payment details are never exposed to the caller.

Here's an example for a payment gateway, api.example.com, that expects a JSON body with cardholder data (CHD). You call the invoke HTTP call action operation like this:

curl -s -X POST \
  --url 'http://localhost:8123/api/pvlt/1.0/data/actions/http_call?reason=AppFunctionality' \
  -H 'Authorization: Bearer pvaultauth' \
  -H 'Content-Type: application/json' \
  -d '{
  "template_variables": {
    // Map the `payment_details` variable to a Vault global identifier that references the payment_details object in the `payment_details` collection.
    "payment_details":  "pvlt:detokenize:payment_details::bb5e17ce-38b1-4b3f-9b4b-40801f9672d1:",
  },
  "request": {
    "method": "POST",
    // Use the `payment_details.email` property as the `to` query parameter.
    "url": "https://api.example.com/charge",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer <your payment gateway api key>"
    },
    // Use the `payment_details` structure to define the properties to post to the payment gateway. Piiano Vault injects (using string replacement) the stored values before invoking the API.
    "body": "{
      \"holder_name\":\"{{ .payment_details.holder_name }}\",
      \"number\":\"{{ .payment_details.number }}\",
      \"expiration\":\"{{ .payment_details.expiration }}\",
      \"cvv\":\"{{ .payment_details.cvv }}\"
    }"
  }
}'

With this call, you're charging a payment method and keeping your business system out of scope for PCI compliance. You're doing this by calling your payment gateway using a template that references the payment details stored in Piiano Vault.

note

Piiano Vault is not a payment gateway. It is a secure and compliant way to collect sensitive information online. You need to use a payment gateway to process payments. Piiano Vault integrates with payment gateways using a supported payment gateway integration.

Learn more:

On this page