{"method":"POST","path":"https://api.revcent.com/v2/sales/pending","summary":"Create A Pending Sale","description":"Allows the creation of a new pending sale, which will issue a unique sale ID for updating and processing the same pending sale. This will not process payment.
A pending sale allows you to have RevCent save a specific sale with a customer, including payment information, without immediately processing the payment.
The pending sale concept was built to facilitate multi-step and upsell flows, where information and products may be added or changed at different times prior to payment being processed.
You can update a pending sale as many times as you wish via the UpdatePendingSale operation, and process the payment when ready via the ProcessPendingSale operation. View markdown documentation at https://revcent.com/documentation/markdown/mcp/operation/CreatePendingSale.md for an in-depth overview of this operation.","operationId":"CreatePendingSale","requestBody":{"content":{"application/json":{"schema":{"properties":{"campaign":{"type":"string","title":"Campaign ID","description":"A 20 character campaign ID.","minLength":20,"maxLength":20},"iso_currency":{"description":"The three digit ISO 4217 currency code.","type":"string","minLength":3,"maxLength":3},"ip_address":{"description":"The customer IP address.","type":"string"},"credit_card":{"additionalProperties":false,"description":"If you wish to add credit card payment information to the pending sale, which will be used when processing the pending sale for payment.","properties":{"card_number":{"description":"The full credit card number.","type":"string"},"exp_month":{"description":"The credit card expiration month as a one or two digit integer, i.e. MM.","type":"integer"},"exp_year":{"description":"The credit card expiration year as a two digit integer, i.e. YY.","type":"integer"},"card_code":{"description":"The credit card code as a string. Depending on the card type this can be different lengths.","type":"string"},"three_ds":{"description":"Optional 3DS if payment_type is credit_card. If you are using 3DS you can send RevCent the 3DS response values, which RevCent will pass to the processor.","additionalProperties":false,"properties":{"enabled":{"description":"Indicating whether or not RevCent should parse 3DS variables to send to the processor. Must be set to true if using 3DS during checkout and sending 3DS values to the processor. Default is false.","type":"boolean"},"version":{"description":"The 3DS version. Example: '2.1.0' or '2.2.0'.","type":"string"},"eci":{"description":"The eCommerce indicator. Indicates the result of the attempt to authenticate the cardholder. On successful authentications.","type":"string"},"cavv":{"description":"Cardholder Authentication Verification Value. On all successful authentications.","type":"string"},"xid":{"description":"The transaction identifier from authentication processing. Occasionally provided for some card brands.","type":"string"},"directory_server_id":{"description":"A transaction identifier assigned by the directory server. On all successful authentications.","type":"string"},"authentication_response":{"description":"Describing if a customer was successfully verified or attempted. On successful authentications.","type":"string"},"acs_transaction_id":{"description":"Access Control Server (ACS) transaction identifier.","type":"string"},"algorithm":{"description":"3DS algorithm used.","type":"string"},"directory_response":{"description":"3DS directory server response.","type":"string"},"enrollment_response":{"description":"Verify enrollment response/status.","type":"string"},"three_ds_server_transaction_id":{"description":"3DS server transaction id.","type":"string"}},"type":"object"}},"type":"object","required":["card_number","exp_month","exp_year"]},"customer":{"description":"The customer object receives first priority as details when creating a new customer.","additionalProperties":false,"properties":{"first_name":{"type":"string","description":"The customer first name."},"last_name":{"type":"string","description":"The customer last name."},"address_line_1":{"type":"string","description":"The customer first address line."},"address_line_2":{"type":"string","description":"The customer second address line."},"city":{"type":"string","description":"The customer city."},"state":{"type":"string","description":"The customer state."},"zip":{"type":"string","description":"The customer ZIP and or postal code."},"country":{"type":"string","description":"The customer country in three letter ISO 3166-1 alpha-3 format."},"company":{"type":"string","description":"The customer company."},"email":{"type":"string","format":"email","description":"The customer email."},"phone":{"type":"string","description":"The customer phone."}},"type":"object","required":["first_name","last_name","email"]},"bill_to":{"description":"To use as the billing information. If not present the customer object will be used. Useful when simultaneously adding a credit card with separate billing information.","additionalProperties":false,"properties":{"first_name":{"type":"string","description":"The bill to first name."},"last_name":{"type":"string","description":"The bill to last name."},"address_line_1":{"type":"string","description":"The bill to first address line."},"address_line_2":{"type":"string","description":"The bill to second address line."},"city":{"type":"string","description":"The bill to city."},"state":{"type":"string","description":"The bill to state."},"zip":{"type":"string","description":"The bill to ZIP and or postal code."},"country":{"type":"string","description":"The bill to country in three letter ISO 3166-1 alpha-3 format."},"company":{"type":"string","description":"The bill to company."},"email":{"type":"string","format":"email","description":"The bill to email."},"phone":{"type":"string","description":"The bill to phone."}},"type":"object","required":["first_name","last_name","email"]},"ship_to":{"description":"To use as the ship to information. If not present the customer object, or bill_to object will be used if either present in respective order.","additionalProperties":false,"properties":{"first_name":{"type":"string","description":"The shipping first name."},"last_name":{"type":"string","description":"The shipping last name."},"address_line_1":{"type":"string","description":"The shipping first address line."},"address_line_2":{"type":"string","description":"The shipping second address line."},"city":{"type":"string","description":"The shipping city."},"state":{"type":"string","description":"The shipping state."},"zip":{"type":"string","description":"The shipping ZIP and or postal code."},"country":{"type":"string","description":"The shipping country in three letter ISO 3166-1 alpha-3 format."},"company":{"type":"string","description":"The shipping company."},"email":{"type":"string","format":"email","description":"The shipping email."},"phone":{"type":"string","description":"The shipping phone."}},"type":"object","required":["first_name","last_name","email"]},"product":{"description":"The products to include in the sale request.","items":{"description":"An individual product","additionalProperties":false,"properties":{"id":{"title":"Product ID","type":"string","description":"A 20 character product ID.","minLength":20,"maxLength":20},"quantity":{"description":"The quantity being purchased. Default is 1.","type":"integer"},"price":{"description":"The price you wish to charge, if different from the product default price in RevCent.","type":"number","format":"float"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for an individual product when creating a sale. This metadata will be passed to the eventual product sale for the product, which is extremely useful for business metrics.
For example, if an individual product within a sale is an upsell, you can include metadata with name: 'is_upsell' and value: 'true' for that product. This will allow you to easily run product level reports on all upsells by filtering for the metadata name of 'upsell' and value of 'true'."}},"type":"object","required":["id"]},"type":"array"},"shipping":{"description":"Shipping to include in the sale request. Please refer to our Provider Method Table at our knowledge base for the provider and method IDs.","items":{"description":"An individual shipping entry.","additionalProperties":false,"properties":{"amount":{"description":"The amount to charge for the specific shipping entry. A shipping amount can be 0.","type":"number","format":"float"},"provider":{"description":"The shipping provider. This will be included when creating a shipment at a fulfillment center. Please refer to our Provider Method Table at our knowledge base for the correct provider id.","type":"string"},"provider_method":{"description":"The shipping provider method. This will be included when creating a shipment at a fulfillment center. Please refer to our Provider Method Table at our knowledge base for the correct method id corresponding to the provider.","type":"string"},"name":{"description":"An optional name for the shipping entry.","type":"string"},"description":{"description":"An optional description for the shipping entry.","type":"string"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for an individual shipping entry when creating a sale. This metadata will be passed to the eventual shipping item for the sale."}},"type":"object","required":["amount"]},"type":"array"},"tax":{"description":"Tax to charge in the sale request. Can create multiple tax entries to itemize separate taxes.","items":{"description":"An individual tax entry.","additionalProperties":false,"properties":{"amount":{"description":"The amount to charge for the specific tax entry.","type":"number","format":"float"},"name":{"description":"An optional name for the tax entry.","type":"string"},"description":{"description":"An optional description for the tax entry.","type":"string"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for an individual tax entry when creating a sale. This metadata will be passed to the eventual tax item for the sale."}},"type":"object","required":["amount"]},"type":"array"},"coupon":{"description":"Include one or more coupon codes which will be used to automatically apply discounts to a sale.","items":{"description":"An individual tax entry.","additionalProperties":false,"properties":{"coupon_code":{"description":"A coupon code which exists in RevCent.","type":"string"}},"type":"object","required":["coupon_code"]},"type":"array"},"discount":{"description":"Include one or more discount entries which will be used to automatically apply discounts to a sale. Can be a fixed amount or a percentage of the sales total.","items":{"description":"An individual discount entry.","additionalProperties":false,"properties":{"discount_value":{"description":"The coupon discount value relative to the discount_type.","type":"number","format":"float"},"discount_type":{"description":"The coupon discount type, either percent or amount. RevCent will calculate the discount if percent.","type":"string","enum":["percent","amount"]},"name":{"description":"An optional name for the discount entry.","type":"string"},"description":{"description":"An optional description for the discount entry.","type":"string"},"apply_to_product":{"description":"Whether to apply the discount to products purchased. Default is true. Set to false if discount should only apply to shipping.","type":"boolean"},"apply_to_shipping":{"description":"Whether to apply the discount to shipping. Default is true. Set to false if discount should only apply to products purchased.","type":"boolean"}},"type":"object","required":["discount_value","discount_type"]},"type":"array"},"internal_sale_id":{"description":"An optional internal sale ID, i.e. a third party order ID. For records purposes only.","type":"string"},"internal_customer_id":{"description":"An optional internal customer ID, i.e. a third party customer ID. For records purposes only.","type":"string"},"metadata":{"items":{"additionalProperties":false,"properties":{"name":{"type":"string","description":"A name paired to the value for the metadata object. Limited to 100 characters in length.","minLength":1,"maxLength":100},"value":{"type":"string","description":"A value paired to the name for the metadata object. Limited to 255 characters in length.","minLength":1,"maxLength":255}},"type":"object","required":["name","value"]},"type":"array","description":"You have the option to provide metadata for a sale, which will be passed down to all items created as a result of the sale, i.e. the customer, product sales, shipping, tax. This is extremely useful for adding information you wish to view or use for reporting.
Visitor Tracking: If the sale took place on a website, and you have tracking domain DNS set up in RevCent for the website, you must include the following metadata from the visitor/session cookie for the sale:
1. {'name': 'revcent_track_id', 'value': '[the value of visitor/session cookie.revcent_track_id]'}
2. {'name': 'revcent_entry_id', 'value': '[the value of visitor cookie.revcent_entry_id]'}
Offline Payments: For offline payment sales involving a third party payment processor you must include three metadata entries to ensure proper association of the sale within RevCent to the third party:
1. {'name': 'offline_payment_third_party', 'value': 'sezzle | afterpay | klarna | affirm | amazon_pay'}
2. {'name': 'offline_payment_third_party_transaction_id', 'value': '[the transaction ID from the third party]'}
3. {'name': 'offline_payment_third_party_integration_id', 'value': '[the RevCent ID of the third party integration within your account for the third party processor]'}"}},"type":"object","additionalProperties":false,"required":["campaign","customer","product","ip_address"]}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"","properties":{"api_call_id":{"type":"string","description":"A 20 character API call ID.","minLength":20,"maxLength":20},"api_call_unix":{"description":"Unix timestamp of when the API call was initiated.","type":"integer","format":"unix-time"},"code":{"description":"API call response code.","type":"integer","format":"int32","enum":[1]},"campaign_id":{"type":"string","title":"Campaign ID","description":"A 20 character campaign ID.","minLength":20,"maxLength":20},"customer_id":{"title":"Customer ID","type":"string","description":"A 20 character customer ID.","minLength":20,"maxLength":20},"sale_id":{"type":"string","description":"A 20 character sale ID.","minLength":20,"maxLength":20},"result":{"type":"string"}},"type":"object","additionalProperties":false}}},"description":"Use the sale_id value in the response to refer to the same pending sale when updating, processing or cancelling."},"default":{"content":{"application/json":{"schema":{"description":"","properties":{"api_call_id":{"type":"string","description":"A 20 character API call ID.","minLength":20,"maxLength":20},"api_call_unix":{"description":"Unix timestamp of when the API call was initiated.","type":"integer","format":"unix-time"},"code":{"description":"This value indicates that there is an error. Will always be 0.","type":"integer","enum":[0]},"error_code":{"description":"The specific error code.","type":"string"},"message":{"description":"A human readable description of the error.","type":"string"},"result":{"description":"A description of the API call result.","type":"string"}},"title":"APIStandardErrors","type":"object","additionalProperties":false}}},"description":"Error response."}}}