Payments & Billing

Payments & Billing

Webshare has 2 main objects for managing payment & billing:

  • Payment Method: The payment method used in the payment process.
  • Transaction: The transaction created when a payment is completed.

Payment Method

The payment method used in the payment process. There are various payment methods (e.g. card, Stripe Link). All of the payment methods can be accessed via the same API.

You can distinguish payment methods using the type field. All payment methods

Payment method object

Shared fields for payment methods

All payment methods have the following shared fields. Each payment method may have additional fields.

AttributesTypeDescription
idstring

Unique identifier of the payment method instance.

typestring

Unique identifier of the payment type. Example values: StripeCard, LinkPayment

created_atstring

The timestamp of when the payment method was created.

updated_atstring

The timestamp of when the payment method was last updated.

Fields for StripeCard

The fields below are available only when the PaymentMethod.type is StripeCard.

AttributesTypeDescription
brandstring

Brand of the card. Could be mastercard, amex, visa, diners club, jcb or `unionpay

last4string

Last 4 digits of the card.

expiration_yearnumber

Expiration year of the card.

expiration_monthnumber

Expiration month of the card. 6 means June.

In JSON format

stripe_card.json
{
  "id": 1,
  "type": "StripeCard",
  "brand": "visa",
  "last4": "4242",
  "name": null,
  "expiration_year": 2023,
  "expiration_month": 6,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

Fields for LinkPayment

Link payments do not have any additional fields.

link_payment.json
{
  "id": 1,
  "type": "LinkPayment",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

Transaction

The transaction created when a payment is completed.

Transaction object

AttributesTypeDescription
idstring

Unique identifier of the transaction instance.

statusstring

Status of the object. Can be completed or refunded. Partial refunds will show up as refunded.

payment_methodobject

Nested payment method instance.

reasonstring

The reason of this transaction.

amountnumber

The amount of the transaction in USD.

credits_usednumber

The credits used in the transaction.

credits_gainednumber

The credits gained in the transaction (In case of downgrading).

refund_amountnumber

The amount refunded in USD.

refund_datestring

The date the last refund was issued. May be null if no refund was issued. If a user is refunded multiple times for the same transaction, only the last date will be shown.

created_atstring

The timestamp of when this instance was created.

updated_atstring

The timestamp when this instance was last updated.

In JSON format

transaction_object.json
{
  "id": 1,
  "status": "completed",
  "payment_method": {
    "id": 1,
    "brand": "visa",
    "last4": "4242",
    "name": null,
    "expiration_year": 2023,
    "expiration_month": 6,
    "created_at": "2022-06-14T11:58:10.246406-07:00",
    "updated_at": "2022-06-14T11:58:10.246406-07:00"
  },
  "reason": "Upgraded from Free Plan to 100 Proxies with 250 GB bandwidth.",
  "amount": 1.0,
  "credits_used": 0.0,
  "credits_gained": 0.0,
  "refund_amount": 0.0,
  "refund_date": null,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

Pending Payments

Pending payment object

AttributesTypeDescription
idstring

Unique identifier of the pending payment object.

statusstring

Current state of the pending payment. Can be pending, processing, successful or failed.

failure_reasonstring

Set to a user-friendly string if a status is failed. Default is null.

payment_methodobject

Nested payment method instance.

planobject

Nested plan instance.

transactionobject

Nested transaction instance. Only set if the status is successful.

is_renewalboolean

Whether the payment should be used to renew the subscription or immediately change it.

termstring

Term of the payment. Can be monthly or yearly.

created_atstring

The timestamp on when the pending payment was created

updated_atstring

The timestamp when the pending payment was last updated.

completed_atstring

The timestamp when the pending payment status was last updated.

In JSON format

pending_payment_object.json
{
  "id": 1,
  "status": "pending",
  "failure_reason": null,
  "payment_method": 2,
  "plan": 2,
  "transaction": null,
  "is_renewal": false,
  "term": "monthly",
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00",
  "completed_at": null
}
Unpause the subscriptionPayment methods