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 https://api.uship.com/v2/paymentCodes. A Shipper who wishes to activate a payment code must log into their uShip account on web (www.uship.com) 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.


GET

URI https://api.uship.com/v2/listings/{listingId}/paymentCodes/

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

Response

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

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.

 

label
String The localized string for the payment code status. "Active"
shortLabel
String The localized string for the payment code status as shown on a mobile or touch device. "Active"
links
Array Wrapper for the hypermedia link object if the payment code status is pending redemption. -
rel
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"
verb
String

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.
"POST"
href
String This hypermedia reference attribute specifies the URL of the page link destination. This reference link suggests what actions are possible.  "/v2/paymentcodes"
title
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."