Listings Payment Codes

Business Rules | Roles and Permissions

  • The Broker or Carrier who sees the payment code is the Service Provider who completed the shipment for the listing ID.
  • The Shipper who sees the payment code hypermedia link is the one who can release payment for their completed shipment. We recommend that the Shipper does not release the payment for their shipment until the Service Provider has delivered it and feedback has been provided by both parties.

In general, as a Service Provider, you can only receive payment for the shipment you won and delivered if the Shipper provides the corresponding unused payment code.

Currently, third party developers cannot activate a payment code via the API using POST A Shipper who wishes to activate a payment code must log into their uShip account on web ( or on their mobile app. 

Payment Code

What is a payment code?

A payment code is one of the three possible options a Shipper may have when booking with a Service Provider. A payment code is considered a fully pre-funded payment where a shipper pre-funds their uShip account with the total shipping price. In some cases the shipper is presented with a payment code and in some cases the payment is automatically released according to the agreed upon terms. 

For shipments with a payment code, when delivery is completed the customer can release payment from their account or give the payment code directly to the TSP, which is the equivalent of making a non-reversible cash payment. TSPs can only ask for the payment code after the load is delivered when being paid through uShip Payments (exception: shipments of live animals may require payment at pick-up). The shipper agrees that they will release the payment code to the TSP upon delivery of the shipment regardless of damages, delays or any other service level issue that might have occurred during transit. If a shipper refuses to release the payment code, uShip cannot release payment without the shipper’s consent under any circumstance. It is the responsibility of both the TSP and shipper to resolve all monetary disputes, damage claims, breach of contract claims, etc. outside of uShip. 

For pre-funded shipments without a payment code, You authorize uShip to release payment in accordance with the TSP’s payment terms. The funds are made available for withdrawal by the TSP’s uShip account when the payment is released or the code is submitted. 

The description here is not a binding contract. Please refer to the latest uShip User Agreement to understand how a payment code works.



The payment code exists for a Shipping Customer to release payment to a Service Provider once a shipment is complete. 


Field Type Description Example
Integer The sum of payment codes associated with this listing ID. 5
Array Wrapper for the objects. List of payment code usage history associated with the listing ID. -
String System-generated alphanumeric payment code. "A1B2C304"
Container Wrapper for the data set describing the usage status of the payment code. -

Payment code status.

Valid Values:

  • "Activated" - Shipping Customer/Shipper has used the payment code. No hypermedia links array returns.
  • "Pending" - When this status is shown, a corresponding hypermedia link object is also returned.
  • "Withdrawn" - Service Provider has used the payment code. No hypermedia links array returns.


String The localized string for the payment code status. "Active"
String The localized string for the payment code status as shown on a mobile or touch device. "Active"
Array Wrapper for the hypermedia link object if the payment code status is pending redemption. -
String This field describes which object the link is related to such as the ability to complete a function in a certain context. This reference is one of the possible actions that can be done.  "Create"

This field is the HTTP verb associated with the possible action that can be done. 

  • GET - Retrieve an object or array of objects.
  • PUT - Update an existing object or array of objects.
  • POST - Create a new instance of an object or array of objects.
  • DELETE - Remove an object or array of objects.
String This hypermedia reference attribute specifies the URL of the page link destination. This reference link suggests what actions are possible.  "/v2/paymentcodes"
String The descriptive name of the possible action. "activatePaymentCode"

Returned Status Codes

Role Code Message Reason
Shipper 200 OK The hypermedia link exists for a Shipper to the unused payment code associated with the delivered listing. 
Service Provider or Shipper 204 NoContent The Service Provider or Shipper tied to the listing uses the payment code.
Service Provider or Third Party Carrier 403 Forbidden

GET "Permission denied for reason: Not allowed to view payment codes."

POST "Permission denied for reason: User not allowed to activate payment code."

Code 100010: "Payment code already activated."