SellApp

Charges

Charges are a slimmed down, more fluid, version of orders. Similar to orders, they are used to take payment for products/services rendered. Unlike orders, however, charges do not manage/handle product delivery.

This makes charges especially useful as a building block for your external project where you handle/manage product delivery manually.

On this page, we'll dive into the different charge endpoints you can use to manage charges programmatically. We'll look at how to view, create, and update charges.

The charge model

The charge model contains all the information about the charges stores have, including the type, code, and discount amount.

Properties

  • Name
    id
    Type
    integer
    Description

    (read-only) The unique identifier for the Charge object.

  • Name
    url
    Type
    string
    Description

    (read-only) The checkout URL you would direct a customer to. The customer can complete the payment or claim the free item on this URL.

  • Name
    status
    Type
    string
    Description

    (read-only) The current status of the charge. Possible values include PENDING, COMPLETED, VOIDED.

  • Name
    email
    Type
    string
    Description

    The customer's email address. Required.

  • Name
    reference
    Type
    string
    Description

    (optional) An optional reference for the charge.

  • Name
    currency
    Type
    string
    Description

    (conditional) Three-letter ISO currency code. Required if total > 0.

  • Name
    total
    Type
    integer
    Description

    (conditional) The total amount intended to be charged in the smallest currency unit (e.g., cents for USD). Required if currency is provided and the charge is not free. Must be > 0 for paid charges.

  • Name
    return_url
    Type
    string
    Description

    The URL to redirect the customer back to after they complete the checkout process (successfully or not). Required.

  • Name
    webhook
    Type
    string
    Description

    (optional) A URL to send webhook events to for status updates regarding this charge.

  • Name
    payment_method / payment_methods / use_all_payment_methods
    Type
    string/array/boolean
    Description

    (conditional) The specific payment gateway(s) for this charge. Required for paid charges. You can either pass:

    1. One payment method: "payment_method": "STRIPE"
    2. Multiple payment methods (which the customer can select from): "payment_methods": ["PAYPAL", "STRIPE"]
    3. All payment methods configured on your SellApp store: "use_all_payment_methods": true
  • Name
    cancel_url
    Type
    string
    Description

    (optional) A URL to redirect the customer to if they cancel the checkout process.

  • Name
    description
    Type
    string
    Description

    (optional) An optional description for the charge.

  • Name
    coupon_code
    Type
    string
    Description

    (optional) A valid SellApp coupon code to apply to the charge.

  • Name
    created_at
    Type
    timestamp
    Description

    (read-only) Time at which the object was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    (read-only) Time at which the object was last updated.

Note on Amounts: All monetary amounts (like total) are provided in the smallest currency unit (e.g., cents for USD, pence for GBP).

POST/v2/charges

Create a charge

This endpoint allows you to create a new charge object. This can be for a paid transaction or a free item claim.

Required attributes

  • Name
    email
    Type
    string
    Description

    The customer's email address.

  • Name
    return_url
    Type
    string
    Description

    URL for redirection after checkout.

Conditional attributes (for paid charges)

  • Name
    total
    Type
    integer
    Description

    Total amount in smallest currency unit. Required if currency is provided.

  • Name
    currency
    Type
    string
    Description

    3-letter ISO currency code. Required if total is provided.

  • Name
    payment_method / payment_methods / use_all_payment_methods
    Type
    string/array/boolean
    Description

    You can either pass:

    1. One payment method: "payment_method": "STRIPE"
    2. Multiple payment methods (which the customer can select from): "payment_methods": ["PAYPAL", "STRIPE"]
    3. All payment methods configured on your SellApp store: "use_all_payment_methods": true

Optional attributes

  • Name
    reference
    Type
    string
    Description

    Custom reference string.

  • Name
    description
    Type
    string
    Description

    Charge description.

  • Name
    cancel_url
    Type
    string
    Description

    URL for redirection if the user cancels.

  • Name
    webhook
    Type
    string
    Description

    Webhook URL for status updates.

  • Name
    coupon_code
    Type
    string
    Description

    Coupon code to apply.

Request (Paid Charge)

POST
/v2/charges
$request = new HttpRequest();
$request->setUrl('https://sell.app/api/v2/charges');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders([
  'accept' => 'application/json',
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer YOUR_API_TOKEN'
]);

$request->setBody('{
    "reference": "Test Payment",
    "currency": "USD",
    "return_url": "https://store.com/thank-you",
    "webhook": "https://testwebhook.com/test",
    "email": "customer@example.com",
    "total": 10000,
    "payment_method": "PAYPAL"
}');

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Request (Free Charge)

POST
/v2/charges
$request = new HttpRequest();
$request->setUrl('https://sell.app/api/v2/charges');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders([
  'accept' => 'application/json',
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer YOUR_API_TOKEN'
]);

$request->setBody('{
  "email": "customer@example.com",
  "return_url": "https://store.com/thank-you"
}');

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Response

{
  "id": 1,
  "url": "https://sell.app/store/charges/select/1?signature=...",
  "status": "PENDING"
}

The response contains the id of the newly created charge, its initial status (usually PENDING), and the url the customer should be redirected to.

GET/v2/charges/:id

Retrieve a charge

Retrieves the details of an existing charge by its ID. Refer to the charge model section for details on the returned object structure.

Required attributes

  • Name
    id
    Type
    integer
    Description

    The ID of the charge to retrieve.

Request

GET
/v2/charges/:id
$request = new HttpRequest();
$request->setUrl('https://sell.app/api/v2/charges/1');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders([
 'Content-Type' => 'application/json',
 'accept' => 'application/json',
 'Authorization' => 'Bearer YOUR_API_TOKEN'
]);

try {
 $response = $request->send();
 echo $response->getBody();
} catch (HttpException $ex) {
 echo $ex;
}

Response

{
  "id": 1,
  "url": "https://sell.app/store/charges/select/1?signature=...",
  "status": "PENDING",
}
PUT/v2/charges/:id/completed

Mark pending charge completed

Manually marks a pending charge as completed.

This action should only be performed on charges with a PENDING status and where you're certain you've received the funds. Attempting to mark a charge with a different status as completed will result in an error.

Required attributes

  • Name
    id
    Type
    integer
    Description

    The ID of the charge to mark as completed.

Request

PATCH
/v2/charges/:id
$request = new HttpRequest();
$request->setUrl('https://sell.app/api/v2/charges/17/completed');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders([
  'Content-Type' => 'application/json',
  'accept' => 'application/json',
  'Authorization' => 'Bearer YOUR_API_TOKEN'
]);

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Response

{
  "message": "Charge Completed Successfully"
}

Returns a success message upon successful completion. The charge status will be updated to COMPLETED.

PUT/v2/charges/:id/voided

Mark pending charge voided

Manually marks a pending charge as voided (canceled).

This action should only be performed on charges with a PENDING status. Attempting to void a charge with a different status will result in an error.

Required attributes

  • Name
    id
    Type
    integer
    Description

    The ID of the charge to mark as voided.

Request

PATCH
/v2/charges/:id
$request = new HttpRequest();
$request->setUrl('https://sell.app/api/v2/charges/17/voided');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders([
 'Content-Type' => 'application/json',
 'accept' => 'application/json',
 'Authorization' => 'Bearer YOUR_API_TOKEN'
]);

try {
 $response = $request->send();
 echo $response->getBody();
} catch (HttpException $ex) {
 echo $ex;
}

Response

{
  "message": "Charge Voided Successfully"
}

Returns a success message upon successful voiding. The charge status will be updated to VOIDED.