Advance a test subscription's clock
Test environment only: runs one subscription’s reminder, charge or retry now, as if the time had come, and returns it. Use next_charge to run what is next, or a timestamp to run everything due by then. The outcome of a charge follows the sandbox outcome numbers. On the live API this answers 404. Requires the mandates.write permission.
/v1/test-helpers/subscriptions/{id}/advanceAuthorizationBearer token (JWT) · headerrequiredA token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.
idstringrequiredThe subscription's id, like sub_0f1d6a3c7b114a549a3b6f1c2f0e8f6e.
Idempotency-KeystringrequiredA unique value you generate for this attempt, at most 255 characters. Send the same value when you retry the same request: it is answered once, however many times you send it. Reusing a value with a different body is refused with 409 idempotency_key_reused.
application/jsontostringrequirednext_charge, or an RFC 3339 timestamp.
The subscription after the step.
idstringrequiredreferencestringrequiredstatusstringrequiredincomplete: waiting for the customer. incomplete_expired: they declined or never answered; see declineReason. trialing: approved, with the first charge still to come. active: charging on schedule. past_due: every retry of a cycle failed; pastDueBehavior says what happens next. unpaid: past due with pastDueBehavior keep_charging. paused: no charges. canceled: see cancelReason. completed: reached endDate or maxCycles.
incompleteincomplete_expiredtrialingactivepast_dueunpaidpausedcanceledcompletedcustomerobjectrequiredShow propertiesHide properties
phonestringrequirednetworkstringmtntelecelpaymentMethodstringrequiredmobile_moneywalletpriceDataobjectrequiredShow propertiesHide properties
amountstringrequiredA decimal string in major units.
currencystringrequiredintervalstringrequireddayweekmonthintervalCountintegerrequired1feestringrequiredThe fee the customer pays on each charge, fixed when the subscription was created. A decimal string in major units.
totalAmountstringrequiredWhat the customer pays on each charge: priceData.amount plus fee.
startDatestring<date>requiredendDatestring<date>maxCyclesintegerbillingTimestringrequiredtimezonestringrequiredretryobjectrequiredShow propertiesHide properties
afterDaysinteger[]pastDueBehaviorstringrequiredcancelpausekeep_chargingdescriptionstringconsentobjectrequiredHow the customer agrees.
Show propertiesHide properties
channelstringrequirednetwork: their network asks them to approve. first_charge: the first charge's prompt is the agreement. pin: they approve with their PIN in the iSmartPay app.
networkfirst_chargepinexpiresAtstring<date-time>When the request lapses if the customer has not answered.
consentedAtstring<date-time>nextChargeAtstring<date-time> | nullrequiredWhen the next charge is due, or null when none is.
cyclesChargedintegerrequiredHow many cycles have been paid.
cancelAtPeriodEndbooleanrequiredcancelAtstring<date-time>When a subscription set to end at its period end will end.
cancelReasonstringPresent when canceled: you canceled it, the customer canceled the agreement with their network, or iSmartPay did.
businessnetworkplatformdeclineReasonstringPresent when incomplete_expired.
declinedno_responsepausedBystringPresent when paused. platform means iSmartPay stopped charging; contact support.
businessplatformcreatedAtstring<date-time>requiredupdatedAtstring<date-time>requiredThe request is not valid. message says which field.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The token is missing, expired or not valid. Get a new one from the token endpoint.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The request was understood and refused. Common causes: the token is not an API credential's (forbidden); the credential is for the other environment (environment_mismatch); it does not have the permission this operation needs (forbidden); a limit was reached (limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit); or iSmartPay has suspended or deactivated the business (business_suspended, business_deactivated). A suspended business's API credentials stop exchanging for tokens, so a request made with a token issued just before the suspension is refused with business_suspended.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Nothing was found with that reference or number. For utilities, product_not_found means no product has that productId.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
A service behind the API did not answer usably. If the request was a POST, retry with the same Idempotency-Key and body. A party lookup the provider rejects is provider_error.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The API is temporarily unable to tell which environment it serves (environment_unknown), utility purchases are not available right now (utilities_unavailable), a settlement destination could not be name-checked just now (destination_verification_unavailable; retry the same request), or hosted checkout is not set up on this deployment (checkout_unavailable). Retry shortly, except for checkout_unavailable, which lasts until the deployment is configured.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.
The request took too long. If it was a POST, its outcome is unknown: retry with the same Idempotency-Key and body, or read it back by reference. A party lookup the provider does not answer is provider_timeout: check again before relying on it.
errorobjectrequiredShow propertiesHide properties
codestringrequiredA stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.
messagestringrequiredReadable detail for a person. For any 5xx it is always the fixed text internal server error.