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.

Every string field must be a JSON string here, unlike in Create payment link, and a field of another type may be ignored rather than refused. After the JSON object, the body may have only white space.

Example

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

curl https://api.gjold.com/v1/subscribers/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 500 charge failed: {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

Every charge that fails answers 500, with a message that starts with charge failed: and names the party that failed, the acquirer or one of ours, and its reason:

HTTP/1.1 500 charge failed: nets error: not sufficient funds

HTTP/1.1 500 charge failed: clearhaus error: card expired

v1 does not say whether a decline may pass. {why} is the acquirer's reason, which acquirers word differently, so read it for your logs and support, not to branch on. Treat a card that has expired, been blocked, or been reported lost, or a payer who stopped your charges, as final, and have the payer renew the subscriber; try anything else again later, with a new key, but not the same day. See When a charge fails and the knowledge base's Declined charges.

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 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, a failure included. A new attempt after a failure needs a new key. 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.