# API Reference Comprehensive reference for integrating with CargoSprint API endpoints. SprintPay lets partners discover cargo facilities, retrieve charges, submit payments, and download receipts and invoices programmatically. Access is granted per partner — contact your CargoSprint relationship manager to request credentials. ## Authentication Every endpoint uses OAuth 2.0 client credentials. Request an access token, then send it as a bearer token on subsequent calls. The token request and the calls that follow authenticate differently: - **`POST /oauth2/token`** uses HTTP Basic authentication with your client ID and client secret. - **Every other endpoint** uses `Authorization: Bearer `. `X-APP-ID: ` is required on **every** request, including the token request. It is issued with your credentials and sent exactly as provided. Tokens are valid for one hour. Cache and reuse them rather than requesting one per call, and request a new token when the current one expires. A `401` is always returned *before* a request is processed, so it never indicates a payment that partially completed. It is safe to request a new token and retry once. Do not retry other error responses automatically. ## Environments A staging environment is available for integration work. Staging and production are fully isolated: payments made in staging settle against sandbox processors and have no effect on production billing. Staging holds a partial copy of production reference data, so some identifiers valid in production may not resolve there. ## Requests and responses Payment requests are submitted as an array and each item is processed independently. **The HTTP status stays `200` even when individual items fail**, so inspect the `saleStatus` of every element in the response rather than relying on the status code. An item with `saleStatus` of `ERROR` did not move money. ## Errors Two kinds of error can be returned, and they are handled differently: - **Transport and authorization errors** apply to every endpoint and are returned as standard HTTP status codes — `400` for a malformed request, `401` for missing or expired credentials, `403` where access is not permitted, `404` where a record does not exist, and `5xx` for a temporary failure. These are described once here and are not repeated on each operation. - **Per-item business errors** are specific to payment submission. They are returned inside a `200` response on the individual item, in `saleResponse`, and describe why that item was not accepted — for example a facility that could not be found, a missing required field, or a payment detected as a duplicate of one already submitted. Where an endpoint returns an error unique to it, that error is documented on the endpoint itself. ## Not currently supported The following are handled outside the API today, and are worth designing around rather than waiting for: - Refunds, voids and partial payments - Webhooks or payment status callbacks — the response to a payment request is the source of truth Version: 1.0.0 License: CargoSprint Terms of Use ## Servers Production ``` https://{service}.cargosprintgroup.com ``` Variables: - `service`: Service host for the endpoint being called. Default: "cart" Enum: "oauth", "facilities", "cart", "invoices", "payments" Staging ``` https://{service}-staging.cargosprintgroup.com ``` Variables: - `service`: Service host for the endpoint being called. Default: "cart" Enum: "oauth", "facilities", "cart", "invoices", "payments" ## Security ### basicAuth Client ID and client secret, used only on the token endpoint. Type: http Scheme: basic ### bearerAuth Access token returned by the authorization endpoint. Type: http Scheme: bearer Bearer Format: JWT ### appId Account identifier issued with your credentials. Required on every request, including the token request, and sent exactly as provided. Type: apiKey In: header Name: X-APP-ID ## Download OpenAPI description - [API Reference](https://developer.cargosprint.com/_bundle/sprintpay/openapi.yaml) ## Oauth - [POST /oauth2/token](https://developer.cargosprint.com/sprintpay/openapi/oauth/getauthorizationtoken.md): Exchange client credentials for an access token. Send the credentials using HTTP Basic authentication. ## Facilities - [GET /facilities](https://developer.cargosprint.com/sprintpay/openapi/facilities/getfacilities.md): Search the facility catalog. Supply at least one filter. Results are paginated. - [GET /getFacility/{id}](https://developer.cargosprint.com/sprintpay/openapi/facilities/getfacility.md): Retrieve a single facility. When the facility is served by an integration, the response includes an `integration` block giving the supported operations, the query fields required to fetch charges, and - [GET /facility/{facilityId}/lookup](https://developer.cargosprint.com/sprintpay/openapi/facilities/getfacilitycharges.md): Retrieve the charges an integration holds for a shipment. Call this before paying a facility that has an `integration` block, then submit the returned charges in the payment request. Build the request ## Cart - [POST /payment](https://developer.cargosprint.com/sprintpay/openapi/cart/makepayment.md): Submit one or more payments. Each item is processed independently: the HTTP status remains `200` and unsuccessful items are returned with `saleStatus` of `ERROR`, so every element of the response shou ## Invoices - [GET /external/invoices/details](https://developer.cargosprint.com/sprintpay/openapi/invoices/getinvoicedetails.md): Retrieve invoice details for a transaction. Invoices are produced on the nightly billing cycle, so an invoice may not be available immediately after a payment. - [GET /external/downloadInvoices](https://developer.cargosprint.com/sprintpay/openapi/invoices/getinvoices.md): Download the invoice for a transaction as a PDF or XLSX document. ## Payments - [GET /external/paymentConfirmation](https://developer.cargosprint.com/sprintpay/openapi/payments/getpaymentconfirmation.md): Download the payment confirmation document for a completed transaction.