Payment Import Format

This section describes how to provide a payment config and payment methods to the Bento. Note that the import service may not be required for this, as a payment method import is only needed if not providing a subscription import, and the tenant config setup is a separate manual process.

{
  "$ref": "#/definitions/paymentMethodSchema",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "paymentMethodSchema": {
      "type": "object",
      "properties": {
        "paymentMethods": { 
          "type": "array", 
          "items": {
            "type": "object", 
            "properties": {
              "customerId": { 
                "type": "string", 
                "minLength": 1,
                "description": "The unique identifier for the client, distinct from payment provider"
              }, 
              "source": {
                "type": "string",
                "enum": ["BRAINTREE", "STRIPE"],
                "description": "The payment provider"
              },
              "token": {
                "type": "string",
                "minLength": 1,
                "description": "The customer's payment method token/ID from the payment provider"
              },
              "providerCustomerId": {
                "type": "string",
                "minLength": 1,
                "description": "The customer id from the payment provider"
              }
            },
            "required": ["customerId", "source", "token", "providerCustomerId"],
            "additionalProperties": false
          },
          "description": "Payment methods, required if not importing subscriptions"
        }
      },
      "required": ["paymentMethods"],
      "additionalProperties": false
    }
  }
}

Field Descriptions

• paymentMethods - customer payment methods, only required if not performing a subscription import.

  • customerId - the customer ID used to identify the customer in the database or customers import.

  • source - the payment provider, e.g. BRAINTREE or STRIPE.

  • token - the payment method token from the payment provider.

  • providerCustomerId - the customer ID from the payment provider.

Example

{
  "paymentMethods": [
    {
      "customerId": "5555555",
      "source": "BRAINTREE",
      "token": "asdfasdkfjasdf",
      "providerCustomerId": "123456789" 
    }
  ]
}

Payment Provider Configuration

On top of payment methods, we require configuration for communicating with your payment provider. Due to the sensitive nature of this data, this will be shared via a different mechanism which will be discussed with your Bento sales representative.

The data is expected to comply with the following schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Payment Config",
  "description": "A merchant payment config, to be provided separate to import",
  "type": "object",
  "properties": {
    "merchant": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "paymentConfig": {
          "type": "object",
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "providerName": { "enum": ["BRAINTREE"] },
                "merchantId": { "type": "string" },
                "publicKey": { "type": "string" },
                "privateKey": { "type": "string" },
                "environment": { "enum": ["sandbox", "production"] }
              },
              "required": ["merchantId", "providerName", "publicKey", "environment"]
            },
            {
              "type": "object",
              "properties": {
                "providerName": { "enum": ["STRIPE"] },
                "secretKey": { "type": "string" }
              },
              "required": ["providerName", "secretKey"]
            }
          ]
        }
      },
      "required": ["name", "paymentConfig"]
    }
  },
  "required": ["merchant"]
}

Field Descriptions

• merchant - the configuration for the payment merchant.

  • name - A human-readable name for the merchant, e.g. your company name.

  • providerName - The name of the payment provider.

  • merchantId (Braintree) - The ID of your company's account with the specified payment provider.

  • publicKey (Braintree) - the Braintree account's public key.

  • privateKey (Braintree) - the Braintree account's private key.

  • environment (Braintree) - the type of account, sandbox or production.

  • secretKey (Stripe) - the Stripe account's secret key.

Where do I find my merchant ID?

• Stripe: See Stripe documentation

• Braintree: See Locating your Braintree credentials

• Shopify: Contact Shopify Support

FAQ

Why is this import step optional?

Since payment method tokens are required for the creation of a subscription contract, we make things easier by only requring a separate payments import if they're not being provided in the subscription contract import format.