Charge subscriber

Charge a subscriber's saved card, without the payer. We send the charge to your acquirer as a merchant-initiated transaction, and answer when it is authorized, and captured unless you say not to, or when it has failed.

Request

• {subid} is the subscriber's "id", from seq.

The key needs the charge permission.

Headers

Fields

An address you send is this charge's, in place of the subscriber's whole, and one you leave out is the subscriber's.

Example

Charge a month of a subscription, with a key made for that month and its first attempt:

curl https://api.gjold.com/v2/{shopid}:sub:19/charge \
    -u {apikey} \
    -H 'Idempotency-Key: sub19-2026-12-try1-7f3a9c2e5b1d4f60' \
    -d @charge.json

{
    "orderid": "M-7192-2026-12",
    "items": [
        {
            "name": "Membership, December",
            "total": "99 DKK"
        }
    ],
    "autocapture": true
}

Response

We answer 200 OK with the charge, a transaction, once the acquirer has authorized it, and captured it with "autocapture":

{
    "type": "charge",
    "id": 1043,
    "totals": {
        "authorized": "99 DKK"
    }
}

Seq returns the whole transaction too, as a charge, with its act of capture if it had "autocapture". A charge is never partly authorized: if the bank approves only part of the amount, we void that, and the charge fails with 402 transient {acquirer} error: partial authorization.

Headers

Timing

A charge waits for the acquirer, once to authorize, and again to capture: a second or two, as a rule, but up to 1 minute per call with Clearhaus, or 10 minutes with Nets, when the acquirer is slow. See Timeouts.

Errors

Declines

A charge that the acquirer declines, or that it does not answer in time, fails with 402, and a message whose first word says whether to try again:

HTTP/1.1 402 permanent clearhaus error: card expired

HTTP/1.1 402 transient nets error: not sufficient funds

{why} is the acquirer's reason, for your logs and support, which acquirers word differently. Branch on the first word, never on the rest. A declined charge leaves no transaction, so seq does not return it; record it yourself.

When the acquirer did not answer in time, the payer's bank may have authorized the charge without our knowing. There is then no transaction to capture, so the bank releases the amount after some days; until then, the payer may see it held. Waiting a day before the next try, as for any transient failure, keeps two holds from piling up.

Other errors

Besides the errors that any request can give, which Errors lists:

Retrying

If the connection breaks before you have the answer, send the request again with the same Idempotency-Key: a charge still running is waited for, and a finished one answers as before. Without a key, you can't know whether the charge went through, and a second request charges the payer twice. For the same reason, never charge the same subscriber twice at once.

See also

Charging subscribers, and in the knowledge base, Stored credentials and Declined charges.