Rappi Payless API v2

These are the specifications for the Rappi Payless API methods and resources. If you haven't reviewed the Introduction, Servers and Authentication, and Rappi Payless Integrations Guidelines sections, please do so before exploring this document. Rappi Payless API v2 OAS3 file

Authentication

HTTP Authentication

Scheme: bearer, Format: JWT access token
The access token obtained from exchanging your Rappi-assigned credentials.

Payment Authorization

POST /pos/barcodes/{barcode}/authorization

This endpoint is invoked when the point of sale (POS) must provide a payment authorization request. The transaction may be declined if Rappi finds inconsistencies against the order details in its database.

Request Example

# You can also use wget

curl -X POST https://microservices.dev.rappi.com/api/cpgops-integrations/pos/barcodes/{barcode}/authorization \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{"totalValue":60.67,"retailStoreId":1002,"totalTaxes":10.92,"taxesDescription":{"IVA":18},"totalDiscount":2.29,"products":[{"retailId":2098308092,"quantity":1,"units":2,"value":39.98,"discount":0},{"retailId":2098308145,"quantity":0.345,"units":1,"value":20.69,"discount":2.29}]}'

Request Parameters

Parameter	Type	In	Description
`barcode` required	string	path	The code scanned from a picker's mobile (or manually typed-in). This code will always be a 6-digit number associated with an order (see fall back option for further information.
`body` required	object	body
`» totalValue` required	number	body	Amount to be collected by this payment.
`» retailStoreId`	string	body	Unique store identifier in your systems; usually the store identifier from your ERP.
`» totalTaxes`	number	body	Total amount of taxes collected on this purchase.
`» taxesDescription`	object	body	Description of the collected taxes; the key:value pair MUST follow the format TAX_NAME:TAX_RATE, e.g., `{ "IVA": 18 }`.
`» totalDiscount` required	number	body	Total discount SHOULD be the sum of simple product markdowns, single or multi SKUs bundle discounts, and any discounts associated with the form of payment.
`» products` required	[object]	body
`»» retailId` required	string	body	Unique SKU identifier in your systems; usually not the EAN (GTIN) but the product identifier from your ERP.
`»» quantity` required	number	body	Weight in Kg for weighable items. Those are the items from the deli, meat, or fruit and vegetable sections, that get weighed on scales. For unit-based items `quantity` MUST be 1.
`»» units` required	integer	body	Number of units scanned of each SKU. For random weight items, the `units` property MUST always be `1`.
`»» value` required	number	body	Total value of each individual SKU in the purchase, including simple markdown discounts; e.g., the regular unit price of a SKU is $5.60, the cashier scanned 2 units, and it's marked down by 10%. The property value should be `10.08`.
`»» discount` required	number	body	Total discount from simple markdown applied to a SKU; following the example in the previous property, the value of the `discount` should be `1.12`.

Responses

Status	Description
`200` OK	Success–transaction authorization approved by Rappi.
`400` Bad Request	Transaction authorization declined.
`401` Unauthorized	The request was signed with an invalid or expired authorization token
`403` Forbidden	Transaction authorization forbidden. This error occurs when the barcode and the order to authorize belong to another retailer; it can happen as the result of a badly typed barcode.
`404` Not Found	Invalid barcode error. This error occurs when the barcode used to authorize the order does not exist or has expired.
`406` Not Acceptable	Transaction authorization declined
`500` Internal Server Error	This is an issue with the server, not the request.

Status Code 200

Name	Description
`» message` string	The transaction authorization returned on this property is represented by a JWT token.

Status Code 400

Name	Description
`» code` integer	The HTTP error code enums: 400,
`» message` string	Human readable description of the error enums:

Status Code 403

Name	Description
`» code` integer	The HTTP error code enums: 403,
`» message` string	Human readable description of the error enums:

Status Code 404

Name	Description
`» code` integer	The HTTP error code enums: 404,
`» message` string	Human readable description of the error enums:

Status Code 406

Name	Description
`» code` integer	The HTTP error code enums: 406,
`» message` string	Human readable description of the error enums: Unacceptable order,

Retrieve Order Details

GET /pos/barcodes/{barcode}/order

This endpoint is invoked when the POS needs to retrieve the order details from Rappi before check-out starts. It SHOULD be used in scenarios where the POS needs the customer's identification or loyalty program number to apply exclusive discounts.

Request Example

# You can also use wget

curl -X GET https://microservices.dev.rappi.com/api/cpgops-integrations/pos/barcodes/{barcode}/order \
  -H 'Accept: application/json' \
  -H 'X-RAPPI-COUNTRY: AR' \
  -H 'X-RAPPI-CHANNEL: B2B' \
  -H 'Authorization: Bearer {access-token}'

Request Parameters

Parameter	Type	In	Description
`X-RAPPI-COUNTRY` required	string	header	The country of operation for a partner retailer. It accepts two-letter country codes in the ISO 3166 alpha-2 format. Accepts: AR, BR, CL, CO, CR, EC, MX, PA, PE, UY
`X-RAPPI-CHANNEL` required	string	header	This identifies the type of client interacting with the cashier in store. Accepts: B2B
`barcode` required	string	path	The payment code scanned from a picker's mobile (or manually keyed-in). This code will always be a 6-digit random number associated with an order.

Responses

Status	Description
`200` OK	Success–details of an order associated with the scanned barcode returned.
`401` Unauthorized	The request was signed with an invalid or expired authorization token
`404` Not Found	The resource or record you're requesting doesn't exist.
`500` Internal Server Error	This is an issue with the server, not the request.

Status Code 200

Name	Description
`» order` object
`»» orderId` integer	Unique identifier of an order in Rappi.
`»» createdAt` string(date-time)	UTC timestamp when the customer placed the order.
`» client` object
`»» identificationNumber` string	User identification number.
`»» identificationType` integer	User identification type.
`» products` [object]
`»» id` integer	Unique SKU identifier in Rappi catalog.
`»» retailId` string	Unique SKU identifier in your systems; usually not the EAN (GTIN) but the product identifier from your ERP.
`»» quantity` number	Weight in Kg for random weight items. Those are the items from the deli, meat, or fruit and vegetable sections, that get weighed on scales. For unit-based items, `quantity` will have the package volume, e.g., `quantity` for a 500ml bottle of Coke would be `500`.
`»» units` integer	Number of units scanned of each SKU. For random weight items, the `units` property will always be `1`.
`»» value` number	Total value of each individual SKU in the purchase, including simple markdown discounts; e.g., the regular unit price of a SKU is $5.60, customer purchased 2 units and it's marked down by 10%. The property value will be `10.08`.

Upload Product Catalog

PUT /testing/products

Sandbox This endpoint uploads a catalog of products to your Sandbox environment. It's required to allow the creation of orders for development, testing automation, and quality assurance purposes.
The upload operation performs an upsert, meaning any uploaded products matching an SKU identifier (retail_id) in Rappi's database will be updated with fresh information received in the file, otherwise the new product will be created.

Request Example

# You can also use wget

curl -X PUT https://microservices.dev.rappi.com/api/cpgops-integrations/testing/products \
  -H 'Content-Type: multipart/form-data' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{"file":"string"}'

Request Parameters

Parameter	Type	In	Description
`body` required	object	body	Your sandbox product catalog must be provided in an Excel (.xlsx) file. It must be smaller than 2 MB and adhere to the following schema.
`» file` required	string(binary)	body

Responses

Status	Description
`200` OK	Success–file uploaded
`400` Bad Request	There was a problem with the file you uploaded, e.g., "The max file size is 2MB".
`401` Unauthorized	The request was signed with an invalid or expired authorization token
`500` Internal Server Error	This is an issue with the server, not the request.

Status Code 200

Name	Description
`» message` string	The success message will include a file processing id (int) you can use to verify the status of your catalog creation or update, e.g., "The file is being processed. Please check the results using the id 32".

Status Code 400

Name	Description
`» code` integer	The HTTP error code enums: 400,
`» message` string	Free text describing the error enums:

Verify Product Catalog Upload

GET /testing/products/upload-results/{resultId}

Sandbox This endpoint verifies the status of a product catalog creation or update in your sandbox.

Request Example

# You can also use wget

curl -X GET https://microservices.dev.rappi.com/api/cpgops-integrations/testing/products/upload-results/{resultId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Request Parameters

Parameter	Type	In	Description
`resultId` required	integer	path	The operation identifier returned from a catalog upload.

Responses

Status	Description
`200` OK	Success response
`400` Bad Request	Catalog processing is still running.
`401` Unauthorized	The request was signed with an invalid or expired authorization token
`500` Internal Server Error	This is an issue with the server, not the request.

Status Code 400

Name	Description
`» code` integer	The HTTP error code enums: 400,
`» message` string	Free text describing the error enums:

Generate Dummy Orders

POST /testing/orders

Sandbox This endpoint generates a set of dummy orders with multiple scenarios for your testing and QA routines.

Request Example

# You can also use wget

curl -X POST https://microservices.dev.rappi.com/api/cpgops-integrations/testing/orders \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{"store_id":"string"}'

Request Parameters

Parameter	Type	In	Description
`body` required	object	body
`» store_id` required	string	body	Unique store identifier in your systems; usually the store identifier from your ERP.

Responses

Status	Description
`200` OK	Success–set of dummy orders returned; each scenario in the response body will adhere to the schema`{ "order_id": "string", "shopper": "string" }`.
`400` Bad Request	The request failed; more details in the response body.
`401` Unauthorized	The request was signed with an invalid or expired authorization token
`500` Internal Server Error	This is an issue with the server, not the request.

Status Code 200

Name	Description
`» valid` object
`» invalid_state` object
`» invalid_storekeeper` object
`» different_retailer` object
`» invalid_high_price` object
`» invalid_low_price` object

Status Code 400

Name	Description
`» code` integer	The HTTP error code enums: 400,
`» message` string	Free text describing the error enums:

Generate Payment Code

POST /pos/orders/{orderId}/barcode

Sandbox This endpoint generates a payment code (barcode) associated with an order in our database.

Request Example

# You can also use wget

curl -X POST https://microservices.dev.rappi.com/api/cpgops-integrations/pos/orders/{orderId}/barcode \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Request Parameters

Parameter	Type	In	Description
`orderId` required	integer	path	Unique identifier of an order created by a customer in the sandbox environment, the id of your dummy orders.

Responses

Status	Description
`200` OK	Success–barcode object returned.
`401` Unauthorized	The request was signed with an invalid or expired authorization token
`404` Not Found	The resource or record you're requesting doesn't exist.
`500` Internal Server Error	This is an issue with the server, not the request.

Status Code 200

Name	Description
`» order_id` integer
`» barcode` string
`» status` string
`» created_at` string(date-time)
`» sent_at` string(date-time)
`» expires_at` string(date-time)
`» show_until` string(date-time)
`» prefix` string
`» refreshed` boolean
`» qr` object
`»» order_id` integer
`»» barcode` string
`»» status` string
`»» created_at` string(date-time)
`»» sent_at` string(date-time)
`»» expires_at` string(date-time)
`»» show_until` string(date-time)
`»» prefix` string
`»» refreshed` boolean

undefined

Authentication#

HTTP Authentication

Payment Authorization#

Request Example#

Request Parameters#

Responses#

Retrieve Order Details#

Request Example#

Request Parameters#

Responses#

Upload Product Catalog#

Request Example#

Request Parameters#

Responses#

Verify Product Catalog Upload#

Request Example#

Request Parameters#

Responses#

Generate Dummy Orders#

Request Example#

Request Parameters#

Responses#

Generate Payment Code#

Request Example#

Request Parameters#

Responses#

Authentication

Payment Authorization

Request Example

Request Parameters

Responses

Retrieve Order Details

Request Example

Request Parameters

Responses

Upload Product Catalog

Request Example

Request Parameters

Responses

Verify Product Catalog Upload

Request Example

Request Parameters

Responses

Generate Dummy Orders

Request Example

Request Parameters

Responses

Generate Payment Code

Request Example

Request Parameters

Responses