Payment Request

Creates an SMS Billing payment request and returns the page your customer pays on. Send the customer to redirect_url; you'll hear the result through postbacks and they'll be returned to your redirect_url or failed_url.

https://api.vendreo.com/v1/sms/request-payment

One-off payment

curl --location --request POST 'https://api.vendreo.com/v1/sms/request-payment' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
    "application_key": "{APPLICATION_KEY}",
    "sms_product_id": "{SMS_PRODUCT_ID}",
    "amount": 1500,
    "reference_id": "123456",
    "description": "Chat credit",
    "redirect_url": "https://example.com/success",
    "failed_url": "https://example.com/failed",
    "options": "optional string"
  }'

Subscription

A subscription product charges its own price, so leave out amount.

curl --location --request POST 'https://api.vendreo.com/v1/sms/request-payment' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
    "application_key": "{APPLICATION_KEY}",
    "sms_product_id": "{SMS_PRODUCT_ID}",
    "reference_id": "123456",
    "description": "VIP membership",
    "redirect_url": "https://example.com/success"
  }'

Request


application_key	required Your SMS Billing Payment Profile's application key.
sms_product_id	required The ID of an active SMS Billing product, from SMS Billing → Products.
amount	conditional In pence, from 1 to 4000 (£40.00). Required for a one-off product; must be left out for a subscription.
reference_id	required Your own reference (session ID, order ID). Returned in every postback. Up to 255 characters.
description	required What the customer is paying for.
redirect_url	required Where the customer goes after paying.
failed_url	optional Where the customer goes if the payment fails or expires. Defaults to `redirect_url`.
options	optional Any string; returned in every postback.

Response

{
    "redirect_url": "https://pay.vendreo.com/sms-payment/9d41a2c6-2f0e-4c8a-9a51-2b7f0c3e8d14",
    "payment_request_id": 1201,
    "payment_request_uuid": "9d41a2c6-2f0e-4c8a-9a51-2b7f0c3e8d14",
    "meta": {
        "tracing_id": "8f3b6c1e-5d2a-4f7b-9c0e-1a2b3c4d5e6f"
    }
}

Errors

Status	When
403	SMS Billing isn't enabled on your account, or the application key isn't an SMS Billing Payment Profile's.
422	A field is missing or invalid, for example an inactive product, an amount over £40.00, or an amount sent for a subscription product.

Payment status

The status in postbacks moves through these values.

Status	Meaning
PENDING	Waiting for the customer to enter their number.
AWAITING_TEXT	On a computer: waiting for the customer to text the code word.
OPT_IN_SENT	We've texted the customer asking them to reply PAY AGREE.
OPT_IN_DELIVERED	That text reached their phone.
CHARGING	The customer agreed and we're charging their phone bill.
COMPLETED	Paid.
FAILED	Not paid. See `failure_reason`.
EXPIRED	The customer didn't reply in time.
CANCELLED	The customer started again with another number, or replied STOP.

Sky Mobile

Sky customers are billed by premium text messages, which add up to the amount. If the customer runs out of credit part-way through a payment, we keep trying to take the rest each day for up to 30 days, and the payment stays CHARGING until then. You'll receive sms_payment_completed if it is all taken, or sms_payment_failed if not. If nothing at all could be taken, the payment fails straight away.

Failure reasons

failure_reason	Meaning
opt_in_not_sent	We couldn't send a text to the number.
opt_in_undelivered	The text couldn't be delivered to the number.
no_reply	The customer didn't reply PAY AGREE in time.
no_text	On a computer, the customer didn't text the code word in time.
stopped_by_customer	The customer replied STOP.
network_not_supported	The customer's network doesn't support phone bill payments.
amount_not_available_on_network	The amount can't be charged on the customer's network (on Sky, amounts must be a multiple of 50p).
charge_rejected	The network declined the charge, for example on some pay-as-you-go or business accounts.
charge_failed	The network couldn't take the payment. On Sky, this includes the customer being out of credit.
charge_request_failed	We couldn't reach the network.
no_result	The network didn't confirm the payment within 72 hours. If it confirms later, you'll receive `sms_payment_completed`.
daily_cap	The number has reached its £150.00 daily limit.
already_subscribed	The number already has a live subscription to this product.