[1.23.0] Paying for Shipment

Warning!

Resource available only in the following countries: PL, IT

Paying for shipment in offer mode


On this page

 

Authentication

Access to the resource requires a valid access token.




Paying for Shipment

At the time of offer selection, the other offers (not selected) are deleted.

Attention! Asynchronous processing.

Because the process of buying a shipment is asynchronous the server will return a response without changes related to the buy itself (status change, tracking number assignement) because that data will be available only after some time

POST /v1/shipments/:id/buy

Parameters

ParameterTypeDescriptionValidationAvailability
offer_idIntegerOffer ID available for the shipment being paid

The attribute is required.

  • The offer has to be in the following statuses available  or selected (if a previous payment attempt was unsuccesful)
PL, IT

Example request:

curl -X POST https://api-shipx-pl.easypack24.net/v1/shipments/1/buy -H 'Authorization: Bearer token' -H 'Content-Type: application/json' -d '{
  "offer_id": 1456
}'

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
	"href": "https://api-shipx-pl.easypack24.net/v1/organizations/1/shipments/1",
	"id": "1",
	"parcels": [
		{
			"id": "small package",
			"template": "small",
			"dimensions": {
				"length": "80",
				"width": "360",
				"height": "640",
				"unit": "mm"
			},
			"weight": {
				"amount": "25",
				"unit": "kg"
			},
			"tracking_number": null
		}
	],
	"custom_attributes": {
		"target_point": "KRA010",
		"dropoff_point": null,
		"sending_method": "parcel_locker",
		"dispatch_order_id": 1
	},
	"sender": {
		"id": "123",
		"name": "Nazwa",
		"company_name": "InPost S.A.",
		"first_name": "Jan",
		"last_name": "Nowak",
		"email": "sender@email.com",
		"phone": "888000000",
		"address": {
			"id": "123",
			"street": "Malborska",
			"building_number": "130",
			"city": "Kraków",
			"post_code": "30-624",
			"country_code": "PL"
		}
	},
	"receiver": {
		"id": "123",
		"name": "Nazwa",
		"company_name": null,
		"first_name": null,
		"last_name": null,
		"email": "sender@email.com",
		"phone": "888000000",
		"address": null
	},
	"created_at": "2015-09-06T19:21:00.000+02:00",
	"cod_amount": {
		"amount": 12.50,
		"currency": "PLN"
	},
	"insurance": {
		"amount": 25,
		"currency": "PLN"
	},
	"reference": "Order No. 12345",
	"is_return": false,
	"tracking_number": null,
    "external_customer_id": "8877xxx",
	"offers": [
		{
    		"id": 1456,
    		"carrier": {
      			"id": "inpost_locker",
      			"name": "InPost Paczkomaty",
				"description": "InPost Paczkomaty - Przesyłki paczkomatowe."
    		},
    		"service": {
      			"id": "inpost_locker_standard",
    			"name": "Paczkomatowa Standardowa",
				"description": "Przesyłka paczkomatowa standardowa."
    		},
    		"status": "selected",
			"valid_to": null,
    		"rate": 2.02,
    		"currency": "PLN",
    		"unavailability_reasons": null
		}
	],
	"selected_offer": {
    	"id": 1456,
    	"carrier": {
      		"id": "inpost_locker",
      		"name": "InPost Paczkomaty",
			"description": "InPost Paczkomaty - Przesyłki paczkomatowe."
    	},
    	"service": {
      		"id": "inpost_locker_standard",
      		"name": "Paczkomatowa Standardowa",
			"description": "Przesyłka paczkomatowa standardowa."
    	},
    	"status": "selected",
		"valid_to": null,
    	"rate": 2.02,
    	"currency": "PLN",
    	"unavailability_reasons": null
	},
	"transactions": []
}

Error Information

Errors that may appear when paying for a shipment:

  • resource_not_found - User has no access to the resource or the shipment does not exist.
  • offer_unavailable - Offer is in a different status than available  or selected 
  • transaction_failed - If the payment processing was not succesful
  • offer_expired - Offer is expired (offers are available 5 minutes after they have been generated)



Asynchronous Shipment payment

To retrieve information about the succesful purchase of the shipment, in the organisation settings define a url for sending shipment_confirmed  events. This will result in ShipX sending the following information to the url.

POST https://{{configuration_url}}
Content-Type: application/json
{
	"event_ts":"2015-12-08 19:42:42 +0100",
	"event":"shipment_confirmed",
	"organization_id":1,
	"payload": {
		"shipment_id":1234567890,
		"tracking_number":"681549342531876019900138"
	}
}