TRtruelayer
Payments

Create payment

Create a new payment

This API must be called using a backend bearer token.

post/v3/payments

Request

  • Base URL
    https://api.truelayer-sandbox.com
  • URL
    https://api.truelayer-sandbox.com/v3/payments
  • Auth
    OAuth 2
    Client credentials
    Token URL: https://auth.truelayer.com/connect/token scopes: payments

Headers

Idempotency-Keystring required

An idempotency key to allow safe retrying without the operation being performed multiple times. The value should be unique for each operation, e.g. a UUID, with the same key being sent on a retry of the same request.

Tl-Signaturestring required

A JWS with detached content, signed with your private key. See Request Signing

X-Forwarded-Forstring

Used to collect and record end-user IP address. The first IP address in the list will be used as the end-user IP address.

X-Device-User-Agentstring

Used to improve end-user's authentication experience based on device type. If omitted, the User-Agent header will be used instead.

Request body

amount_in_minorinteger required

A 'cent' value representing the amount, e.g. 100 = 1GBP or 100 = 1EUR

currency'GBP' | 'EUR' required
metadataMetadata

Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a key with a maximum length of 40 characters and a non-null value with a maximum length of 500 characters.

Example request

{
  "amount_in_minor": 1,
  "currency": "GBP",
  "payment_method": {
    "provider_selection": {
      "filter": {
        "countries": [
          "GB"
        ],
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ],
        "provider_ids": [
          "mock-payments-gb-redirect"
        ],
        "excludes": {
          "provider_ids": [
            "ob-exclude-this-bank"
          ]
        }
      },
      "remitter": {
        "account_holder_name": "Mike Smith"
      }
    },
    "beneficiary": {
      "merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
      "account_holder_name": "Ben Eficiary",
      "reference": "payment-ref",
      "statement_reference": "payment-ref"
    }
  },
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c",
    "name": "Remi Terr",
    "email": "remi.terr@aol.com",
    "phone": "+447777777777",
    "date_of_birth": "1990-01-31",
    "address": {
      "address_line1": "40 Finsbury Square",
      "address_line2": "The Gilbert",
      "city": "London",
      "state": "London",
      "zip": "EC2A 1PX",
      "country_code": "GB"
    },
    "political_exposure": "current"
  },
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "related_products": {
    "signup_plus": {}
  },
  "authorization_flow": {
    "provider_selection": {},
    "scheme_selection": {},
    "redirect": {
      "return_uri": "https://my-site.com/payment-return"
    },
    "form": {
      "input_types": [
        "text"
      ]
    },
    "consent": {},
    "user_account_selection": {}
  },
  "hosted_page": {
    "return_uri": "https://my-domain.com/my-return-page",
    "country_code": "GB",
    "language_code": "en",
    "max_wait_for_result": 3
  },
  "risk_assessment": {
    "segment": "Flights"
  },
  "sub_merchants": {
    "ultimate_counterparty": {
      "url": "https://truelayer.com",
      "mcc": "1234",
      "address": {
        "address_line1": "40 Finsbury Square",
        "address_line2": "The Gilbert",
        "city": "London",
        "state": "London",
        "zip": "EC2A 1PX",
        "country_code": "GB"
      }
    }
  }
}

Response

Payment

OR
OR
OR

Example response

{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
  },
  "resource_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXltZW50X2lkIjoiMGFmZDFmNmEtZjYxMS00OGNlLTk0ODgtMzIxMTI5YmIzYTcwIiwiaWF0IjoxNTE2MjM5MDIyfQ.awUcg4OfxW8lNGB0HUdSfcEpCAiMg_zHudX95EsqvtE",
  "hosted_page": {
    "uri": "https://payment.truelayer.com/payments?lng=en#payment_id=0afd1f6a-f611-48ce-9488-321129bb3a70&resource_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXltZW50X2lkIjoiMGFmZDFmNmEtZjYxMS00OGNlLTk0ODgtMzIxMTI5YmIzYTcwIiwiaWF0IjoxNTE2MjM5MDIyfQ.awUcg4OfxW8lNGB0HUdSfcEpCAiMg_zHudX95EsqvtE&return_uri=https%3A%2F%2Fmy-domain.com%2Fmy-return-page"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.