api documentation - solution25com/paytrace-payment-shopware-6-solution25 GitHub Wiki

PayTrace Plugin - API Documentation

This document describes the external PayTrace API endpoints that the PayTrace Plugin for Shopware 6 interacts with. These endpoints are used internally by the plugin to tokenize payments, process transactions, manage vaulted credit cards, and handle ACH (eCheck) payments.

Generate Client Token

Endpoint:
POST /v3/payment-fields/token

Description:
Generates a token (client key) required to securely tokenize card details via PayTrace's PT Protect frontend library.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "clientKey": "token_abc123xyz456"
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 422,
  "data": [
    {
      "detail": "ensure this value has at most 12 characters",
      "type": "VALIDATION",
      "code": "CONSTRAINT",
      "field": "header/X-Integrator-Id"
    }
  ]
}

Protect Sale Endpoint

Endpoint:
POST /v3/card/sale/pt-protect

Description:
Processes a payment transaction using a one-time token and encryption key created by the Protect.js UI.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "hpf_token": "your_protect_js_token",
  "enc_key": "your_protect_js_encryption_key",
  "amount": 100.25,
  "billing_address": {
    "street": "123 Main St",
    "street2": "Apt 1",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98101"
  },
  "billing_name": "John Smith",
  "merchant_id": 123456
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "response_code": 101,
    "response_message": "Your transaction was successfully approved.",
    "transaction_id": "125553243",
    "approval_code": "VTLMC1",
    "approval_message": "NO  MATCH - Approved and completed",
    "avs_response": "No Match",
    "csc_response": "Match",
    "masked_card_number": null,
    "supplementary_data": null,
    "emv_details": null,
    "surcharge_ineligibility_reason": null,
    "surcharge_amount": "0.0",
    "requested_amount": "100.25",
    "total_amount": "100.25"
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 422,
  "data": [
    {
      "detail": "field required",
      "type": "VALIDATION",
      "code": "REQUIRED",
      "field": "body/amount"
    }
  ]
}

Protect Authorization Endpoint

Endpoint:
POST /v3/card/authorize/pt-protect

Description:
Authorizes a payment using a one-time token and encryption key generated by Protect.js.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "hpf_token": "your_protect_js_token",
  "enc_key": "your_protect_js_encryption_key",
  "amount": 100.25,
  "billing_address": {
    "street": "123 Main St",
    "street2": "Apt 1",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98101"
  },
  "billing_name": "John Smith",
  "merchant_id": 123456
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "response_code": 101,
    "response_message": "Your transaction was successfully approved.",
    "transaction_id": "125553247",
    "approval_code": "AXS858",
    "approval_message": "NO  MATCH - Approved and completed",
    "avs_response": "No Match",
    "csc_response": "Match",
    "masked_card_number": null,
    "requested_amount": "100.25",
    "total_amount": "100.25"
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 422,
  "data": [
    {
      "detail": "field required",
      "type": "VALIDATION",
      "code": "REQUIRED",
      "field": "body/amount"
    }
  ]
}

Capture Endpoint

Endpoint:
POST /v3/card/batch/capture

Description:
Finalizes a previously authorized transaction by capturing the specified amount.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "merchant_id": 123456,
  "batch_items": [
    {
      "transaction_id": "123456789",
      "custom_dba": "Doing Business As Test Company",
      "amount": 100.25
    }
  ]
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": [
    {
      "transaction_id": "125785595",
      "status": "success",
      "status_code": 200,
      "data": {
        "response_code": 112,
        "response_message": "Your transaction was successfully captured.",
        "transaction_id": "125785595"
      }
    }
  ]
}

Example Error Response:

{
  "status": "success",
  "status_code": 422,
  "data": [
    {
      "transaction_id": "125785595",
      "status": "error",
      "status_code": 422,
      "data": {
        "detail": "The Transaction ID that you provided could not be captured. Only uncaptured, approved authorizations can be captured.",
        "type": "LOGIC",
        "code": "CONSTRAINT",
        "error_id": 816
      }
    }
  ]
}

Token Generation Endpoint

Endpoint:
POST /v3/token

Description:
Generates a one-time token used to securely transmit sensitive payment data collected via Protect.js UI.

Content-Type:
application/x-www-form-urlencoded

Example Request Body:

grant_type=client_credentials
client_id=your-client-id
client_secret=your-client-secret

Successful Response:

{
  "status": "success",
  "status_code": 201,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "dXNlcl9yZWZyZXNoX3Rva2Vu...",
    "token_type": "Bearer",
    "expires_in": 900,
    "refresh_expires_in": 3600,
    "username": "your-username"
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 401,
  "data": [
    {
      "detail": "Incorrect username",
      "type": "INTERNAL_REMOTE",
      "code": "ERROR"
    }
  ]
}

Refund Endpoint

Endpoint:
POST /v3/card/batch/refund

Description:
Processes batch refunds for previously captured transactions.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "merchant_id": 123456,
  "batch_items": [
    {
      "transaction_id": "123456789",
      "custom_dba": "Doing Business As Test Company",
      "amount": 100.25
    }
  ]
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": [
    {
      "transaction_id": "125557849",
      "status": "success",
      "status_code": 200,
      "data": {
        "response_code": 106,
        "response_message": "Your transaction was successfully refunded.",
        "transaction_id": "125557849"
      }
    }
  ]
}

Example Error Response:

{
  "status": "success",
  "status_code": 422,
  "data": [
    {
      "transaction_id": "125784882",
      "status": "error",
      "status_code": 422,
      "data": {
        "detail": "Refund amount can not exceed the original settled amount. Previous refunds against this transaction count towards the original transaction amount.",
        "type": "LOGIC",
        "code": "CONSTRAINT",
        "error_id": 819
      }
    },
    {
      "transaction_id": "12584880",
      "status": "error",
      "status_code": 422,
      "data": {
        "detail": "The Transaction ID that you provided was not found.",
        "type": "LOGIC",
        "code": "CONSTRAINT",
        "error_id": 811
      }
    }
  ]
}

Customer Create Endpoint

Endpoint:
POST /v3/customer/create/pt-protect

Description:
Creates a new customer profile with a saved payment method using the Protect.js token and encryption key.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "hpf_token": "your_protect_js_token",
  "enc_key": "your_protect_js_encryption_key",
  "merchant_id": 123456,
  "billing_address": {
    "name": "John Smith",
    "street_address": "123 Main St",
    "street_address2": "Apt 1",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98101",
    "country": "US"
  },
  "customer_label": "cust_001_card_1"
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "customer_id": "cust_001",
    "message": "Customer profile created successfully."
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 422,
  "data": [
    {
      "detail": "Invalid billing address data.",
      "type": "VALIDATION",
      "code": "REQUIRED",
      "field": "billing_address.street_address"
    }
  ]
}

Customer Sale Endpoint

Endpoint:
POST /v3/card/sale/customer/{customer_id}

Description:
Processes a payment using a stored (vaulted) customer card.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "amount": 100.25,
  "merchant_id": 123456
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "response_code": 101,
    "response_message": "Your transaction was successfully approved.",
    "transaction_id": "126789456",
    "approval_code": "XYZ123",
    "approval_message": "Approved and completed",
    "avs_response": "Match",
    "csc_response": "Match",
    "masked_card_number": "************1111",
    "requested_amount": "100.25",
    "total_amount": "100.25"
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 422,
  "data": [
    {
      "detail": "Missing or invalid customer ID",
      "type": "VALIDATION",
      "code": "REQUIRED",
      "field": "customer_id"
    }
  ]
}

Void Transactions Endpoint

Endpoint:
POST /v3/card/batch/void

Description:
Voids one or more credit card transactions that are still pending settlement. Only unsettled transactions are eligible for voiding.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "merchant_id": 123456,
  "batch_items": [
    {
      "transaction_id": "123456789",
      "custom_dba": "Void transaction: 123456789"
    }
  ]
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": [
    {
      "transaction_id": "123456789",
      "status": "success",
      "status_code": 200,
      "data": {
        "response_code": 111,
        "response_message": "Your transaction was successfully voided.",
        "transaction_id": "123456789"
      }
    }
  ]
}

Example Error Response:

{
  "status": "success",
  "status_code": 422,
  "data": {
    "detail": "The Transaction ID that you provided could not be voided. Only transactions that are pending settlement can be voided.",
    "type": "LOGIC",
    "code": "CONSTRAINT",
    "error_id": 818
  }
}

Delete Customer Profile Endpoint

Endpoint:
DELETE /v3/customer

Description:
Deletes a vaulted customer profile and all associated stored payment methods from the PayTrace system using the customer ID.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "response_code": 162,
    "status_message": "The customer profile for 0197158d87607366af51ddd91111b482_Card_1/test test was successfully deleted.",
    "customer_id": 11450726
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 404,
  "data": [
    {
      "detail": "No matching customer id.",
      "type": "RESOURCE",
      "code": "NOT_FOUND"
    }
  ]
}

ACH Payment (eCheck) Endpoint

Endpoint:
POST /v3/checks/payment

Description:
Processes an electronic check (ACH) payment using the customer's bank account details.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "std_entry_class": "WEB",
  "billing_name": "John Doe",
  "billing_email": "[email protected]",
  "shipping_name": "John Doe",
  "bank_account": {
    "account_number": "123456789",
    "routing_number": "011000015",
    "account_type": "Checking"
  },
  "amount": "150.00",
  "merchant_id": "123456",
  "billing_address": {
    "street": "123 Main St",
    "street2": "Suite 4",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98101"
  },
  "shipping_address": {
    "street": "123 Main St",
    "street2": "Suite 4",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98101"
  }
}

Successful Response:

{
  "message": "Success",
  "transaction_id": "b349f1ec-91c2-4d8f-9a71-24f0ae1d5a4b",
  "tran_date": "2025-05-30T10:25:45Z",
  "tran_type": "1",
  "std_entry_class": "WEB",
  "description": "WEB ACH Payment",
  "amount": "150.00",
  "customer_name": "John Doe",
  "account_number_trunc": "3456",
  "routing_number_trunc": "0006",
  "account_type": "Checking",
  "transaction_status": "ACCEPTED",
  "deposit_id": "dep_57845a91acdd"
}

Example Error Response:

{
  "status": "error",
  "status_code": 422,
  "data": [
    {
      "detail": "There was a problem with your e2ee (client side encryption).",
      "type": "LOGIC",
      "code": "UNPROCESSABLE"
    }
  ]
}

Get Customer Endpoint

Endpoint:
GET /v3/customer

Description:
Returns detailed information about a customer's vaulted profile, including their payment methods and stored details.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "customer_id": 11450728,
    "merchant_id": 85774,
    "customer_label": "0197158d87607366af51ddd91111b482_Card_2",
    "name": "John Smith",
    "card_masked": "549974xxxxxx0057",
    "address": "test",
    "country": "US",
    "zip_code": "12345",
    "city": "test",
    "state": "CA",
    "exp_month": "02",
    "exp_year": "28",
    "custid": "0197158d87607366af51ddd91111b482_Card_2"
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 404,
  "data": [
    {
      "detail": "No matching customer id.",
      "type": "RESOURCE",
      "code": "NOT_FOUND"
    }
  ]
}

Protect Sale and Create Customer Endpoint

Endpoint:
POST /v3/card/sale/pt-protect/customer/

Description:
Processes a credit card sale using a one-time token via Protect.js. If a customer_label is provided, the card is vaulted and associated with the customer.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "hpf_token": "b04bb67e7c624edcbe129e8b2f3a1223",
  "enc_key": "VBgVfZc2Bd0IsP7F7D1xnF==",
  "amount": "150.00",
  "merchant_id": "85774",
  "billing_name": "John Doe",
  "billing_address": {
    "street": "123 Main St",
    "street2": "Suite 4",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98101"
  },
  "customer_label": "customerId_Card_1"
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "response_code": 165,
    "response_message": "Your transaction was successfully approved and customer profile was created.",
    "transaction_id": "125557852",
    "approval_code": "TAS039",
    "approval_message": "NO  MATCH - Approved and completed",
    "avs_response": "No Match",
    "csc_response": "Match",
    "requested_amount": "150.00",
    "total_amount": "150.00",
    "customer_id": 11451687
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 422,
  "data": [
    {
      "detail": "field required",
      "type": "VALIDATION",
      "code": "REQUIRED",
      "field": "body/customer_label"
    }
  ]
}

Create Customer Profile From Transaction

Endpoint:
POST /v3/customer/create/by-transaction/

Description:
Creates a vaulted customer profile by referencing a completed transaction.

Request Headers:

Authorization: Bearer <your-access-token>
Content-Type: application/json
X-Integrator-Id: <your-integrator-id>

Example Request Body:

{
  "transaction_id": "f932d392-12e4-4cdd-b0ea-84766b4d3f13",
  "billing_address": {
    "name": "John Doe",
    "street_address": "123 Main St",
    "street_address2": "Suite 4",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98101",
    "country": "US"
  },
  "customer_label": "12345_Card_1"
}

Successful Response:

{
  "status": "success",
  "status_code": 200,
  "data": {
    "response_code": 160,
    "status_message": "The customer profile for 12345_Card_1/John Doe was successfully created.",
    "customer_id": 11451690
  }
}

Example Error Response:

{
  "status": "error",
  "status_code": 400,
  "data": [
    {
      "detail": "Please provide a unique customer ID.",
      "type": "LOGIC",
      "code": "CONSTRAINT",
      "error_id": 171
    }
  ]
}