ToolStation - Internal Docs
Routes

Payments

Introduction

This page outlines the API routes for payment processing in the Toolstation E-Com API, covering operations such as managing payment methods, generating client tokens, and handling PayPal interactions.

List of Routes for Payments

  1. /payments/_ping
  2. /payments/methods
  3. /payments/methods/{token}
  4. /payments//methods/{token}/create-nonce

Important Step to follow:

  • Bearer Token Required
    Before making any requests, you need to generate a token. This token will be used for all the requests in this section.
  • Header Required
    x-toolstation-customer-id:- This header is required for all requests in this section. You need to pass the customer ID in this header.

GET: payments/_ping

  • Method: GET
  • Controller: PingController
  • Description: Endpoint to check if the Payments is valid and running successfully. This is a common endpoint for health checks or status pings.

POST: payments/methods

  • Controller: PaymentMethodController
  • Method: POST
  • Request: CreatePaymentMethodRequest
  • Description: Endpoint for creating a new payment method.

The store function is a public method that creates a new payment method for a customer using the Braintree payment gateway. It takes a CreatePaymentMethodRequest object as input, retrieves the customer object from the Braintree gateway, filters existing cards for duplicates, creates a new payment method, and returns a JSON response with a success message and regenerated nonce (if applicable).

public function store(CreatePaymentMethodRequest $request)
{
    // Function implementation goes here
}
  • Error Response:-
    Status: 403 Forbidden
    {
  "error": {
      "code": "401.99",
      "message": "Unauthorized - Token Invalid or Expired",
      "info": "https://developers.example.com",
      "data": null
  }
}

GET: payments/methods

  • Controller: PaymentMethodController
  • Method: GET
  • Request: Request
  • Description: Endpoint for creating a new payment method.

The showCustomer function retrieves a customer's information from Braintree, handles duplicate credit cards, and creates a new account if necessary, while ensuring secure handling of sensitive data.

public function showCustomer(Request $request)
{
    // Function implementation goes here
}
  • Positive Response:
    • Status: 200 OK
    • Response:
      {
  "id": "CWW0206XXXX",
  "merchantId": "d9753wzyyXXSWS",
  "firstName": "ehksahdei",
  "lastName": "kandel",
  "company": null,
  "email": "xxx@gmail.com",
  "phone": null,
  "internationalPhone": {
    "countryCode": null,
    "nationalNumber": null
  },
  "fax": null,
  "website": null,
  "createdAt": {
    "date": "2024-08-09 06:33:11.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "updatedAt": {
    "date": "2024-08-09 06:33:11.000000",
    "timezone_type": 3,
    "timezone": "UTC"
  },
  "customFields": [],
  "globalId": "Y3VzdG9tZXJfQ1dXMDIwNjg4MTY",
  "creditCards": [],
  "addresses": [],
  "paypalAccounts": [],
  "applePayCards": [],
  "googlePayCards": [],
  "venmoAccounts": [],
  "visaCheckoutCards": [],
  "samsungPayCards": [],
  "usBankAccounts": [],
  "graphQLId": "Y3VzdG9tZXJfQ1dXMDIwNjg4MTY",
  "paymentMethods": []
}
  • Error Response:-
    Status: 403 Forbidden
    {
  "error": {
      "code": "401.99",
      "message": "Unauthorized - Token Invalid or Expired",
      "info": "https://developers.example.com",
      "data": null
  }
}

GET: payments/methods/{token}

  • Controller: PaymentMethodController
  • Method: GET
  • Params: $token
  • Description: Endpoint for retrieving a payment method.

The show function retrieves a payment method by token and returns it as a JSON response. If the payment method is not found, it returns a JSON error response with a 404 status code.

public function show($token): JsonResponse
{
    // Function implementation goes here
}
  • Error Response:-
    Status: 403 Forbidden
      {
  "error": {
      "code": "404.99",
      "message": "Resource Not Found",
      "info": "https://developers.example.com",
      "data": {
          "message": "Payment method for token not found"
      }
  }
  }

POST: payments/methods/{token}

  • Controller: PaymentMethodController
  • Method: POST
  • Request: UpdatePaymentMethodRequest
  • Params: $token
  • Description: Endpoint for updating a payment method.

The update function updates a payment method using a gateway and returns a JSON response. It takes two parameters: a request object and a payment method token. The function checks for makeDefault and billingAddress properties in the request data and sets options and billing address arrays accordingly. It then attempts to update the payment method using the gateway and returns a JSON response with the result. If the payment method is not found, it returns a JSON response with a message indicating that the payment method was not found.

public function update(UpdatePaymentMethodRequest $request, string $token)
{
    // Function implementation goes here
}
  • Error Response:-
    Status: 403 Forbidden
      {
  "error": {
      "code": "404.99",
      "message": "Resource Not Found",
      "info": "https://developers.example.com",
      "data": {
          "message": "Payment method for token not found"
      }
  }
  }

DELETE: payments/methods/{token}

  • Controller: PaymentMethodController
  • Method: DELETE
  • Params: $token
  • Description: Endpoint for deleting a payment method.

The delete function attempts to delete a payment method using a given token. If the payment method is not found, it returns a JSON response with an error message. If the payment method is successfully deleted, it returns a JSON response with the result of the deletion.

public function delete(string $token)
{
    // Function implementation goes here
}
  • Error Response:-
    Status: 403 Forbidden
    {
  "error": {
      "code": "401.99",
      "message": "Unauthorized - Token Invalid or Expired",
      "info": "https://developers.example.com",
      "data": null
  }
}

GET: payments/methods/{token}/create-nonce

  • Controller: PaymentMethodController
  • Method: GET
  • Params: $token
  • Description: Endpoint for creating a payment method nonce.

The createNonce function takes a token as input and creates a payment method nonce using the token. It first calls the create method on the payment method nonce object returned by the gateway, passing in the token. If the payment method is found, it returns a JSON response with the nonce and a status code of 201 Created. If the payment method is not found, it returns a JSON response with an error message and a status code of 404 Not Found.

public function createNonce($token)
{
    // Function implementation goes here
}
  • Error Response:-
    Status: 403 Forbidden
    {
  "error": {
      "code": "401.99",
      "message": "Unauthorized - Token Invalid or Expired",
      "info": "https://developers.example.com",
      "data": null
  }
}

Products

The following API routes are available under the products prefix. These routes are cached with public headers and a max age of 60 seconds .

Attribute

Copyright © 2026