Payrails Vault is a key module of our system and works in conjunction with our Payments and Ledger services to help you accept and optimize your payments smoothly.

However, every service at Payrails can be used standalone to adapt to our merchant's use cases. This guide explains how to use the instruments and tokens stored in our Vault with your own Payment service in a way that your infrastructure is never exposed to sensitive data.

We call this feature Vault Proxy because our Payrails Vault stands between your backend and the PSP or third party that will receive the sensitive data. When receiving your request, we replace certain placeholders in the request body with the sensitive information stored in our vault before sending it to the provider. When they respond, we remove the sensitive information and send the response back to you.

Usually, this feature would be used for executing payment authorization requests, but depending on the external provider, it may be that they also require receiving the card in a separate endpoint. For example, Mangopay requires you to first store the card and then execute the payment with their card identifier, so you would use our Proxy only on the first call.

The following is a high-level sequence diagram of the interaction between the services.

Creating Providers

Before being able to use the /proxy endpoint, you have to tell Payrails about the provider with whom you want to exchange information. We need to start by checking their PCI certification to receive full PANs securely. To ensure everyone's security and compliance, Payrails needs to perform certain checks on the provider before starting to send card data. After the security checks are done, we're ready to configure the provider on our system. For example, we need to know which endpoint in the provider itself we need to call on your behalf (providerUrl) and the credentials we need to use for authentication (providerConfig).

Here's an example request for creating a provider in Payrails using the Create a provider.

{
  "name": "checkout",
  "type": "Payment",
  "configSchema": "{\"processor_channel_id\":\"string\"}"
}

And the response will look like this:

{
  "id": "1f3cb3c4-3d8d-4f3c-94ad-30a0a17fde6d",
  "name": "checkout",
  "type": "Payment",
  "status": "active",
  "createdAt": "2021-01-05T10:20:00.000Z",
  "updatedAt": "2022-06-14T11:50:00.000Z"
}

Executing Proxy requests

After the provider is created, you can use the VaultProxy endpoint to send your instruments to the provider.

Example requests to Providers

The following are some examples of some well-known providers and how you should map the card data using our instruments.

Please note that the url field corresponds directly to the endpoint called in the Payment Provider. Contact your Payrails administrator to whitelist URLs before making requests.

{
  "paymentInstrumentId": "eeaac45c-f032-49bc-a8c5-ec99d79b74e2",
  "providerConfigId": "d9699acd-9361-4e11-8d06-b30f41fc6210",
  "url" : "https://checkout-test.adyen.com/v69/payments",
  "headers": {
    "x-API-key": "YOUR_API_KEY"
  },
  "body": {
    "amount": {
      "currency": "USD",
      "value": 1000
    },
    "reference": "your-order-number",
    "paymentMethod": {
      "type": "scheme",
      "number": "{{cardNumber}}",
      "expiryMonth": "{{cardExpiryMonth}}",
      "expiryYear": "{{cardExpiryYear}}",
      "cvc": "{{cardSecurityCode}}",
      "holderName": "{{cardHolderName}}"
    },
    "returnUrl": "https://your-company.com/...",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
  }
}

{
  "paymentInstrumentId": "eeaac45c-f032-49bc-a8c5-ec99d79b74e2",
  "providerConfigId": "d9699acd-9361-4e11-8d06-b30f41fc6210",
  "url" : "https://checkout-test.adyen.com/v69/payments",
  "headers": {
    "x-API-key": "YOUR_API_KEY"
  },
  "body": {
    "amount": 1000,
    "currency": "USD",
    "reference": "some_reference",
    "source": {
      "type": "card",
      "number": "{{cardNumber}}",
      "expiry_month": "{{cardExpiryMonth}}",
      "expiry_year": "{{cardExpiryYear}}",
      "cvv": "{{cardSecurityCode}}",
      "name": "{{cardHolderName}}"
    },
    "payment_type": "Regular",
    "authorization_type": "Final",
    "capture": true,
    "processing_channel_id": "pc_xxxxxxxxxxx",
    "risk": {
      "enabled": false
    },
    "merchant_initiated": true
  }
}

{
  "Tag": "Custom meta",
  "AuthorId": "205062273",
  "DebitedFunds": {
    "Currency": "EUR",
    "Amount": 5000
  },
  "SecureModeReturnURL": "https://mangopay.com/docs/please-ignore",
  "Culture": "EN",
  "BrowserInfo": {
    "AcceptHeader": "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
    "JavaEnabled": true,
    "Language": "en-EN",
    "ColorDepth": 4,
    "ScreenHeight": 1800,
    "ScreenWidth": 400,
    "TimeZoneOffset": 60,
    "UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "JavascriptEnabled": true
  },
  "IpAddress": "b02a:7967:ecc2:d827:cdd0:67d3:6d2f:4fef",
  "Billing": {
    "FirstName": "Alex",
    "LastName": "Smith",
    "Address": {
      "AddressLine1": "100 rue Rivoli",
      "AddressLine2": null,
      "City": "Paris",
      "Region": "Ile-de-France",
      "PostalCode": "75001",
      "Country": "FR"
    }
  },
  "Shipping": {
    "FirstName": "Alex",
    "LastName": "Smith",
    "Address": {
      "AddressLine1": "100 rue Rivoli",
      "AddressLine2": null,
      "City": "Paris",
      "Region": "Ile-de-France",
      "PostalCode": "75001",
      "Country": "FR"
    }
  },
  "Card":{
    "Number":"{{cardNumber}}",
    "ExpirationDate":"{{cardExpiryMonth}}{{cardExpiryYear2Digits}}",
    "CVX":"{{cardSecurityCode}}"
  },
  "CardType":"CB_VISA_MASTERCARD"
}

Variable substitution

Fields of the format {{key}} will be replaced by data contained in your Payrails Payment Instrument.

The following fields are currently supported:

{{cardNumber}}: Card number
{{cardHolderName}}: Card holder name
{{cardSecurityCode}}: Card security code (CVV, CVC, or several other names)
{{cardExpiryMonth}} or {{MM}}: Card expiry month
{{cardExpiryYear}} or {{YYYY}}: Card expiry year
{{cardExpiryYear2Digits}} or {{YY}}: Card expiry year last 2 digits

If the key is not present, the data will be sent as is to the Payment Provider.