NAV
curl

Introduction

Welcome to the Reepay API documentation.

The Reepay API is REST based and designed to have predictable resource-oriented URLs and to use HTTP response codes to indicate API errors.

The Reepay API is formally specified using a OpenAPI 3 Specification. It is a specification standard surrounded by an ecosystem of tools, which includes front-end user interfaces and code generation libraries. We mainly offer an OpenAPI Specification as an API documentation tool, and caution against simply generating client code directly from the specification. The chances are that such code is overly complex and will be difficult to test and maintain. The whole Reepay system is exposed through API, but only a small subset is normally required for common operations such as managing subscriptions and creating one-time charges. A generated client will usually contain mostly unused operations and attributes. Furthermore will the auto generated code ca be rigid regarding object and enum structure. If new fields are added the auto generated code can fail.

Reepay OpenAPI resources:

The specification user-interface allows testing of resource operations using your private API key.

Examples on the use of the API can be found here.

Authentication

Authentication to the Reepay API is done using a private API key. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Most requests require authentication.

API key authentication is done by providing one of your private API keys in the request. You can manage your private API keys from your account. You can have multiple API keys active at one time.

The API key must be provided as the HTTP Basic Auth username.No password needs to be provided. HTTP Basic Auth is performed by sending an Authorization header with value Basic base64('<privatekey>:'). E.g. for private key

priv_12051dfac75143fc827cf63a87f46df3

the value will be

base64('priv_12051dfac75143fc827cf63a87f46df3:') = cHJpdl8xMjA1MWRmYWM3NTE0M2ZjODI3Y2Y2M2E4N2Y0NmRmMzo=

and the complete header will be

Authorization: Basic cHJpdl8xMjA1MWRmYWM3NTE0M2ZjODI3Y2Y2M2E4N2Y0NmRmMzo=

To test base64 encoding the following site can be used www.base64decode.org

Reepay also supports token based authentication where a token is obtained by a login with username and password. This solution can be used if you wish to build an administration solution using the credentials stored at Reepay. Contact Reepay for more information if this is relevant for you.

Response data

All responses from the Reepay API will be in JSON. All responses will contain a unique request identifier in the HTTP headers with name Request-Id. The request-id allows Reepay to find requests in cases where troubleshooting is necessary.

Reepay follows an open for extension, but closed for modification API strategy, meaning that new attributes can be added, but no required attributes are removed. It is important that integrations are implemented to ignore unknown attributes.

Request data

As POST and PUT data the Reepay API accepts application/json content-type. The content-type must be defined in the HTTP header of requests.

Errors

Reepay uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error at Reepay or external systems used by Reepay.

HTTP Status Code Summary

HTTP code Description
200 - OK Everything worked as expected.
400 - Bad Request Illegal operation on a resource
401 - Unauthorized No valid authentication provided
403 - Forbidden Authentication given but not authorized to resource operation
404 - Not Found The requested resource or referenced resources could not be found
405 - Method Not Allowed The used HTTP method is not allowed on the resource
422 - Unprocessable Entity The request could not be interpreted, often missing a required parameter or wrongly formatted parameters
429 - Request limiting exceeded The request is declined either due to request rate limiting (code=122) or concurrent requests limit (code=123).
500-504 - Server Errors An internal error occurred on Reepay’s end

Error response

All non successful 2xx responses will return a generic JSON error response with the following parameters.

{
  "code" : 13,
  "error" : "Subscription expired",
  "http_reason" : "Bad Request",
  "http_status" : 400,
  "path" : "/v1/subscription/WHBBv/expire",
  "timestamp" : "2015-06-12T06:38:33.876+0000",
  "request-id" : "de03e86d0a6d44359b249340f967ddc9",
  "transaction_error" : "credit_card_expired"
}
Parameter Type Description
code integer Reepay API error code. See full list of error codes here
error string Short error message
message string Optional clarifying error message
http_status integer HTTP status code of the error (same as the HTTP response)
http_reason string HTTP reason of the error (same as the HTTP response)
path string The path generating the error response
timestamp string Date when the error occurred. In ISO-8601 extended offset date-time format.
request-id string Unique request id for the failed request.
transaction_error  string Optional transaction error in the case the request involved transaction processing. See table below with possible transaction errors.

Example on the right.

Transaction errors

For requests that involves transaction processing the error response will contain a transaction state and error. The transaction state is a high-level categorization of the error with three categories:

Transaction state Description
hard_declined Irrecoverable payment method errors. The payment method is declined and future attempts will fail.
soft_declined Possible recoverable errors. The payment method or settle of authorization is declined but future attempts may succeed. E.g. insufficient funds on card.
processing_error Errors in the processing chain from Reepay to the acquirer not related to the payment method.

The transaction error will have a more detailed indication of the decline or processing error. Notice that in many cases only limited information is given from payment provider, e.g. card issuer, on the reason for the decline.

Transaction error Description
insufficient_funds Valid payment method but insufficient funds to complete transaction. Ususally a soft decline.
settle_blocked Settle of authorization blocked. Ususally a soft decline.
credit_card_expired Credit card expired
declined_by_acquirer Transaction declined by payment provider for some reason
credit_card_lost_or_stolen Credit card lost or stolen
credit_card_suspected_fraud Credit card suspected fraud
refund_amount_too_high The tried refund amount is too high
authorization_expired Settle failed because the authorization has expired
authorization_amount_exceeded Settle failed because requested amount exceeded authorized amount
authorization_voided Settle failed because authorization has been voided
sca_required Transaction declined by payment provider because strong customer authentication (e.g. 3D Secure) is required
risk_filter_block Transaction was declined by a Reepay Risk Filter rule
fraud_block Transaction was declined by Reepay Fraud Detector
emv_token_deleted EMV token deleted by issuer - cannot be active again
emv_token_suspended EMV token suspended by issuer - might be activated again
acquirer_communication_error Communication with payment provider failed
acquirer_error Error at the payment provider
acquirer_integration_error There is an error in the integration to the payment provider
acquirer_authentication_error Provided authentication credentials are not valid
acquirer_configuration_error Error in the configuration of the payment provider or payment gateway account
acquirer_rejected_error Payment provider rejected this specific transaction. E.g. amount too low or too high.

Webhooks

Reepay can issue webhooks that can be used to keep your system in sync and to take customized actions. Webhooks requires you to have a publicly accessible web server listening on port 80 (HTTP) or 443 (HTTPS). These are the only ports supported. Webhooks can be configured with multiple URL’s to support a redundant setup where the same webhook is sent to multiple URL’s. Below some rules and best practices regarding webhooks:

Webhook content

The webhook content is in JSON and contains the following parameters (example on the right):

{
    "id": "8ab4b56439944e62ababca7954355578",
    "event_id": "680bd8055b5c444bb467dcb731c65bf9",
    "event_type": "invoice_settled",
    "timestamp": "2015-06-25T12:10:00.64Z",
    "signature": "7a591eddc400af4c8a64ff551ff90b37d79471bd2c9a5a2fcd4ed6944f39cb09",
    "customer": "OVAFIJ",
    "payment_method": "ca_b6506f005dce813e408919475f39bffd",
    "payment_method_reference": "cs_4468ca21dfde3c37a5736684cf608111",
    "subscription": "sub001",
    "invoice": "inv-1234",
    "transaction" : "28b1af53d7ecd1c487292402a908e2b3",
    "credit_note" : "a26c1bf5f656f489f295d0c4748dd003",
    "credit" : "inv-12-credit-3241",
}
Parameter Description
id Unique id for webhook. If multiple URL’s are used each request will have different id’s but same event_id.
event_id Id of event triggering webhook (see events).
event_type The event type (see below and events).
timestamp Timestamp in ISO-8601 when the webhook was triggered.
signature Signature to verify the authenticity of the webhook. See below.
customer (Optional) Customer handle. Included if event relates to a customer resource.
payment_method (Optional) Payment method id. Included for the customer_payment_method_added event.
payment_method_reference (Optional) Payment method reference. For a Checkout session the reference will be the session id if it has not been explicitly defined when creating the session.
subscription (Optional) Subscription handle. Included if event relates to a subscription resource.
invoice (Optional) Invoice handle. Is inv-<invoice_number> if invoice was created automatically for subscription. Included if event relates to an invoice resource.
transaction (Optional) For invoice events a transaction id is included if the event was result of a transaction, e.g. a card settle transaction. The transaction id the same as refund id for refunds.
credit_note (Optional) Credit note id. Included if the event relates to an invoice refund, credit or cancellation.
credit (Optional) Credit id. Included if the event is an invoice credit.

Notice that new parameters might be introduced. It is important that webhook reception is implemented to ignore unknown parameters.

Optionally the signature can be used to validate the authenticity of the webhook id and timestamp. It is calculated as follows:

signature = hexencode(hmac_sha_256(webhook_secret, timestamp + id))

That is

The same calculation can be done in the receiving end, allowing authentication of the webhook. The webhook secret is defined in the webhook settings.

Example in PHP:

hash_hmac('sha256', $timestamp . $id, $secret , false);

Example in Java using Apache Commons Codec:

String signature = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, secret).hmacHex(timestamp + id);

Notice that the signature only guarantees that the id and timestamp has not been tampered. Replay attacks would still be possible to using same id and timestamp. Only having id and timestamp in the signature is deliberate as a signature covering all parameters is very inflexible when introducing potential new return parameters. To handle potential replay attacks we recommend to store the id when a webhook has been processed. If the same id is received again it can be ignored just responding with a HTTP 200 OK. This is also an effective way to implement idempotency as recommended above.

An alterntive way to protect the webhook endpoint is to use HTTP Basic Auth. It can be configured for the webhooks in the webhook configuration.

Yet another alternative is to get the full entity status using the API upon receival of a webhook. E.g. get the whole charge object and only rely on the status of this object.

Webhook event types

Webhooks are triggered by events. See event for a complete list if event types and their description. In the Administration and/or using the API, it can be configured which events to generate webhooks for. Not all events will by default generate a webhook.

Webhook retries

Reepay will retry failing webhooks using the following retry intervals: 2 min - 5 min - 10 min - 20 min - 30 min - and then every hour for three days. For test accounts, webhooks will only be retried for 24 hours.

Webhook ordering

Webhooks are delivered in FIFO ordering grouped by customer entity and URL. That is, all webhooks for events relating to the same customer are delivered sequentially and in FIFO order for each URL. E.g. for a combined create customer and subscription operation that results in an invoice to be created right away, the customer created event will be delivered before the subscription created event which will be delivered before the subscription renewal event and invoice created events. The ordering is only guaranteed if webhooks does not fail. A failed webhook will be retried but will not block for subsequent webhook in same grouping.

To limit the number of concurrent webhooks being fired against your system, a limit of five groups is put on each account. As a result at most five concurrent requests will be fired against your system.

We recommend to reduce the error scenarios when receiving webhooks, preferably offloading webhook processing by putting on a queue or in database, and then have an asynchronous job to process the webhooks.

Webhook alerting

In the Reepay administration under Webhook configuration, alerting can be enabled that will send emails to a number of recipients if webhooks fail. An alert will be sent at most once for each failing webhook. To limit the amount of alerts, at most one email will be sent every 30 minutes per account.

Request limiting

Reepay imposes the following request limits on the usage of API.

In the case these limits are exceeded a 429 HTTP error response is returned. The code in the error response indicates if rate or concurrent limit has been exceeded (122 and 123 respectively).

It is unlikely to experience request limits with normal usage of the API, even at high volume. The most common causes for exceeding the limits are bugs, bulk data processing or load testing. Should your requests begin to receive 429 HTTP errors, reduce the frequency of your requests. Each failed request is perfectly safe to retry as rate limiting takes place before any other action and prevents the request from being processed. When reducing your request frequency, we recommend an exponential backoff by first waiting one second before trying again. If your request continues to receive the same response, wait two seconds, then four seconds, etc.

Rate limits for both test and live modes are identical. Requests made in test mode are an accurate representation of what to expect when making live requests. If you are experiencing rate limits but are unable to determine why, please contact us at support@reepay.com.

We urge you to use the API in a fair manner, not introducing unnecessary load. E.g. to use webhooks instead of polling for events, and limit the number of threads to use for bulk operations. We consider it unfair API usage if the API usage is not proportional to the number of entities managed at Reepay. Constantly retrieving all data from Reepay is an example of what we would consider unfair API usage.

Reepay monitors API usage over longer periods to identity excessive API usage. We will try to get in contact on excessive use, but we may be forced to reduce limitis until the matter has been resolved.

List queries

Most top level Reepay API resources have support for list operations where lists of entities can be fetched given different query attributes. The list operations share a common structure for requests and responses.

List queries are intended for specific queries, e.g. invoices for a specific customer and/or subscription, and infrequent on-demand operations to search for entities or to pull bulk data from Reepay. The list queries are not intended as a way to continously synchronize data in own system. This will be considered unfair API usage. Webhooks provide a way to keep data in own system in-sync with Reepay.

Requests

Requests are HTTP GET requests for the list operation on the specific resource. Query attributes are given as query parameters. All operations share this set of query parameters.

Parameter Type Description Example
range string Optional range defining the date and time attribute used to limit the query and also defines the sorting. The sorting is always descending. Each resource offers different range attributes. Each resource have a default range if non is defined. range=created
from localdatetime Optional time range start. The from time is inclusive. Given in local date (and maybe time) according to account timezone. Defaults to one month from to if no interval is given. from=2022-01-01
to localdatetime Optional time range end. The to time is exclusive. Given in local date (and maybe time) according to account timezone. Defaults to now. to=2022-02-01
interval duration Optional interval as an alternative to using from. The interval will be according to to, e.g. one week from to. interval=P1W
size integer Optional page size between 10 and 100. Defaults to 20. size=100
next_page_token string Used to get the next page if query results in multiple pages. Will be returned in response for current page. The above parameters must be the same in all subsequent page requsts. next_page_token=MTYzMjkxNDc4NTAwMDoxMA

Types

Request parameters are given in a number of types given below.

Type Description Example
localdatetime Local date and optional time according to account timezone. Can be given in the following formats:
yyyy-MM-dd
yyyyMMdd
yyyy-MM-ddTHH:mm
yyyy-MM-ddTHH:mm:ss
yyyy-MM-ddTHH:mm:ss.SSS
to=2022-02-01T12:00:00.000
duration Duration in ISO 8601 P1M (one month)
stringlist Some parameters can be lists. E.g. a list of entity states to filter on. Multiple values are defined by using the same parameter multiple times. state=authorized&state=settled
integerinterval Interval written as mathematical interval. [ is from and including. ( is from but excluding. ] is to and including and ) is to but excluding. If no value is defined there will be no limit on either the start or end. amount=[0;20000]0<=amount<=20000
amount=(0;20000]0<amount<=20000
amount=(0;20000)0<amount<20000
amount=(10000;)10000<amount
amount=[5000;5000]amount=5000
localdatetimeinterval Same as integer interval except that values are in localdatetime dunning_success=[2022-01-01;2022-02-01) dunning success in January 2022

Response

All list operations have the same generic response object.

{
    "size": 20,
    "count": 20,    
    "to": "2022-02-01T00:00:00.000",
    "from": "2022-01-01T00:00:00.000",
    "content": [ ... ],
    "range": "created",
    "next_page_token": "..."
}
Parameter Type Description
size integer Used page size
count integer Number of elements in current page. If less than page size it is the last page.
to localdatetime Local date and time range used as to (exclusive)
from localdatetime Local date and time range used as from (inclusive)
content array List of count entities for the page
range string Range attribute limited on
next_page_token string Pagination token to use to get the next page. If not present the last page has been reached.

Pagination

To get all pages of a list query, continue to use the same request parameters except for changing the next_page_token. Once a response has size=count or next_page_token is not returned, the last page has been reached.

Default range interval

The default range interval from to is one month if no specific from or interval is given. To search for all entities a long interval, e.g. interval=P100Y or from=1970-01-01, can be given.

There are exceptions to the default range interval though, if a relation like customer and/or subscription is used as a query attribute. That is, all entities related to another entity can be fetched without specifying a long interval as interval will default to infinity. E.g. all invoices for a customer can be fetched with speficying and interval. There is also an exception if an indexed attributed is used as query attribute. Currently this is limited to email on customer.

Query timeout

A list query can timeout and give error response with HTTP status 400 and code=144. In this case use a smaller time range for the operation. E.g. one month instead of three months.

Examples

Get list of invoices settled in January 2022:

GET https://api.reepay.com/v1/list/invoice?range=settled&from=2022-01-01&to=2022-02-01

Get list of invoices created the last three months with state pending or dunning:

GET https://api.reepay.com/v1/list/invoice?range=created&interval=P3M&state=pending&state=dunning

Searching and pagination

Most top-level Reepay API resources have support for bulk fetches — “list” API methods. For instance you can list invoices, list customers, and list subscriptions. These list API methods share a common structure.

Reepay utilizes page-based pagination, using the query parameters page and size. Pass page to dictate what page you want to show and size to dictate how many items you want per page. Each individual resource will have resource specific filtering.

The generic response is either a page with total number and elements, or a slice lacking these two parameters. Slicing is used for optimization reasons when counting the total number of elements can be too expensive. The generic response contains the following parameters:

{
    "page": 50,
    "size": 50,
    "count": 50,
    "content": [ ... ],
    "total_elements": 500,
    "total_pages": 10,
    "search": "customer:cust0002"
}
Parameter Type Description
page integer Number of current page in paginated list
size integer Page size used
count integer Number of elements in current page
content array List of objects for current page
total_elements integer Total number of elements in paginated list (not included for sclices)
total_pages integer Total number of pages in paginated list (not included for sclices)
search string Optional used search expression (see below)

Example on the right.

For slicing a next page can be requested as long count = size.

Search expression

Most bulk fetches features an option to search. Searching is done using search expressions. A search expression is as a comma separated list of search criteria. A search criteria is on the form:

<parameter_name><operator><value>

The following operators can be used:

Operator Description
: Equals. The parameter value must match value.
; Contains. The value must be contained in the parameter value. For strings case-insensitivity comparison is used.
< Lees than
> Greater than

Example of a search expression for customers:

handle;cust,country:DK

The customer handle must contain cust and the country of the customer must equal DK.

For date and time parameters date and time must be given in ISO-8601. Example:

search=settled>2017-01-10T17:03:10+02:00

Notice that all values must be url encoded.

Testing

Testing different scenarios in Reepay can be done using our Test Payment Gateway and a number of test cards. The test cards are fixed but a number of predefined CVV codes and amounts can be used to trigger different scenarios. Any expiration date can be used as long as it is the current month or in the future.

Test cards

Type Id Number
Visa visa 4111 1111 1111 1111
Visa-DK visa_dk 4571 9940 0006 2336
Dankort dankort 5019 1000 0000 0006
Visa Electron visa_elec 4026 1111 1111 1115
Mastercard mc 5500 0000 0000 0004
American Express amex 3400 000000 00009
JCB jcb 3530 1113 3330 0000
Maestro maestro 6759 0000 0000 0000
Diners diners 3000 0000 0000 04
Discover discover 6011 1111 1111 1117
China Union Pay china_union_pay 6240 0086 3140 1148
Forbrugsforeningen ffk 6007 2200 0000 0004

Recurring token create errors

Errors in the authorization process of adding a recurring card payment method can triggered by the following CVV codes. To trigger additional errors for one-time charging see “Charging errors” below.

CVV Scenario
001 The credit card is declined with due to credit card expired
002 The credit card is declined by the acquirer
003 The credit card is declined due to insufficient funds
004 The authorization is declined due to errors at the acquirer
005 The authorization is declined due to communication problems with the acquirer
006 The authorization is declined due to communication problems with the acquirer (60 second processing time)

Subsequent subscription billing errors

All CVV codes, except the ones above, will result in a successful card authorization. The CVV codes below can be used to trigger different scenarios for subsequent payments. Declines are separated into recoverable and irrecoverable declines. Irrecoverable declines indicates that a payment will never be possible for the card again, e.g. an expired or blocked card. Recoverable declines indicates that successful payments for the card could be possible in the future. This could for example be due to insufficient funds. Reepay will start dunning for recoverable declines, but will regularly try to process payments using the card, as long as a new payment method has not been added.

CVV Scenario
100 The first payment is declined with an irrecoverable error (credit card expired)
101 The first payment is declined with an irrecoverable error (declined by acquirer)
102 The first payment is declined with an recoverable error (insufficient funds)
200 The second payment is declined with an irrecoverable error (credit card expired)
201 The second payment is declined with an irrecoverable error (declined by acquirer)
202 The second payment is declined with an recoverable error (insufficient funds)
300 With a probability of 50% the payment is declined with an irrecoverable error (credit card expired)
301 With a probability of 50% the payment is declined with an irrecoverable error (declined by acquirer)
302 With a probability of 50% the payment is declined with an recoverable error (insufficient funds)

Charging errors

To trigger errors in the process of creating charges and settling authorized charges the cvv 888 can be used in combination with a number of amounts. E.g. a successful authorization can be performed and then a specific amount can be used for the settlement that will result in an error. To trigger the scenarios when charging a saved card the card should be saved with cvv 888. The table below shows the amounts to be used with cvv 888 to trigger errors.

Amount Error state Error code
1000 success
1001 processing_error acquirer_communication_error
1002 processing_error acquirer_error
1003 processing_error acquirer_integration_error
1004 processing_error acquirer_authentication_error
1005 processing_error acquirer_configuration_error
1006 processing_error acquirer_rejected_error
2001 soft_declined insufficient_funds
2002 soft_declined settle_blocked
3001 hard_declined credit_card_expired
3002 hard_declined declined_by_acquirer
3003 hard_declined credit_card_lost_or_stolen
3004 hard_declined credit_card_suspected_fraud
3005 hard_declined authorization_expired
3006 hard_declined authorization_amount_exceeded
3007 hard_declined authorization_voided
1337 hard_declined sca_required (Error for non-SCA payments to mimic PSD2 behaviour)

Payout errors

Payout errors can be triggered by performing payout on cards created with the following CVV codes.

CVV Scenario
501 The credit card is declined with due to credit card expired
502 The credit card is declined by the acquirer
503 The credit card is declined due to insufficient funds
504 The authorization is declined due to errors at the acquirer
505 The authorization is declined due to communication problems with the acquirer
506 The authorization is declined due to communication problems with the acquirer (60 second processing time)

Test data retention

Old test data will automatically be deleted by Reepay. Customers, and all customer releated data e.g. subscriptions and invoices, will be deleted for customers created more than three months ago.

Mail sending limits

For test accounts there is a limit of 100 mails per day. In addition, there is a limit of 10 unique recipients. Mails passing threshold will still be created and shown for invoice and subscriptions, but with a “not allowed” state.

Resending and preview functionality for test accounts are limited to 10 requests per day.

Checkout

The Checkout API for creating Reepay Checkout sessions is a separate API with base url https://checkout-api.reepay.com. Reepay Checkout is described here: https://docs.reepay.com/reference#reepay-checkout-introduction. See below for some quick references to relevant documentation:

Simple create charge session example to the right.

curl -X POST \
  --url https://checkout-api.reepay.com/v1/session/charge \
  -u 'priv_xxxx:' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{
  "order": {
    "handle": "order-12345",
    "customer": {
        "handle": "customer-123",
        "first_name": "John",
        "last_name": "Doe",
        "phone":"+4531313131"
    },
    "amount": 50000
  },
  "accept_url":"https://webshop.com/accept/order-12345",
  "cancel_url":"https://webshop.com/decline/order-12345"
}'

Account

When using Reepay, you have the ability to have multiple accounts.

Use multiple accounts when:

An Example:

The company “Awesome Fitness” have fitness centers in the UK and Denmark, in both countries they have a head office.

They want to ensure customers will be billed in local currency and are billed from the local head office. Furthermore they want to limit access for their support and finance employees to only relevant data.

Therefore they add two accounts to their organization, one for UK and one for DK.

Now, when adding customers and subscription they can specify the account by it’s API Key/Token. (remember to generate an API key for your account after creating)

Values like address,city,locale, phone,website,logo will affect the information your customers receive in E-mails and on hosted pages from Reepay. The currency value will decide the currency for the accounts plans and basically what currency you customers will pay in.

When granting access to new users “Awesome Fitness” can choose to limit access to one account or both.

You can also manage your accounts in our admin.

The Account object

[Swagger:definition:json:Account]

[Swagger:definition:table:Account]

Get account

[Swagger:request:curl:getCurrentAccount]

The above command returns JSON structured like this

[Swagger:response:json:getCurrentAccount]

Get the account object for the current authentication. E.g. private API key.

HTTP Request

GET https://api.reepay.com/v1/account

Returns

Returns the current authenticated Account.

Update account

[Swagger:request:curl:updateAccountJson]

The above command returns JSON structured like this

[Swagger:response:json:updateAccountJson]

Update account by setting the values of the parameters passed, the account is found from the used API key/token. Any parameters not provided will be deleted.

HTTP Request

PUT https://api.reepay.com/v1/account

[Swagger:request:table:updateAccountJson]

Returns

Returns the updated Account object.

Get mail settings

[Swagger:request:curl:getMailSettings]

The above command returns JSON structured like this

[Swagger:response:json:getMailSettings]

Get mail settings for account.

HTTP Request

GET https://api.reepay.com/v1/account/mail_settings

Returns

Returns the MailSettings for the current Account.

Update mail settings

[Swagger:request:curl:updateMailSettingsJson]

The above command returns JSON structured like this

[Swagger:response:json:updateMailSettingsJson]

Update mail settings for account.

HTTP Request

PUT https://api.reepay.com/v1/account/mail_settings

[Swagger:request:table:updateMailSettingsJson]

Returns

Returns the updated MailSettings for the current Account.

Get discount settings

[Swagger:request:curl:getDiscountSettings]

The above command returns JSON structured like this

[Swagger:response:json:getDiscountSettings]

Get discount settings for account.

HTTP Request

GET https://api.reepay.com/v1/account/discount_settings

Returns

Returns the DiscountSettings for the current Account.

Update discount settings

[Swagger:request:curl:updateDiscountSettings]

The above command returns JSON structured like this

[Swagger:response:json:updateDiscountSettings]

Update discount settings for account.

HTTP Request

PUT https://api.reepay.com/v1/account/discount_settings

[Swagger:request:table:updateDiscountSettings]

Returns

Returns the updated DiscountSettings for the current Account.

Get list of private keys

[Swagger:request:curl:getPrivateKeys]

The above command returns JSON structured like this

[Swagger:response:json:getPrivateKeys]

Get private keys for account.

HTTP Request

GET https://api.reepay.com/v1/account/privkey

[Swagger:response:table:getPrivateKeys]

Create private key

[Swagger:request:curl:createPrivateKey]

The above command returns JSON structured like this

[Swagger:response:json:createPrivateKey]

Use an API key to create more API keys for your current account. The current account is decided from the API key you are using.

To create the first API key you must go to our admin in the API key section.

HTTP Request

POST https://api.reepay.com/v1/account/privkey

Returns

[Swagger:response:table:createPrivateKey]

Expire private key

[Swagger:request:curl:expirePrivateKey]

Expire a private key by, remember to use a private key from the same account as the one you are about to expire. You can expire the one you are using as authentication.

HTTP Request

POST https://api.reepay.com/v1/account/privkey/{key}/expire

[Swagger:request:table:expirePrivateKey]

Get list of public keys

[Swagger:request:curl:getPublicKeys]

The above command returns JSON structured like this

[Swagger:response:json:getPublicKeys]

Get public keys for account.

HTTP Request

GET https://api.reepay.com/v1/account/pubkey

[Swagger:response:table:getPublicKeys]

Create public key

[Swagger:request:curl:createPublicKey]

The above command returns JSON structured like this

[Swagger:response:json:createPublicKey]

Create more public keys for the current account.

HTTP Request

POST https://api.reepay.com/v1/account/pubkey

Returns

[Swagger:response:table:createPublicKey]

Expire public key

[Swagger:request:curl:expirePublicKey]

Expire a public key.

HTTP Request

POST https://api.reepay.com/v1/account/pubkey/{key}/expire

[Swagger:request:table:expirePublicKey]

Get webhook settings

[Swagger:request:curl:getWebhookSettings]

The above command returns JSON structured like this

[Swagger:response:json:getWebhookSettings]

Get webhook settings. See webhook documentation in introduction. The webhook settings consist of:

HTTP Request

GET https://api.reepay.com/v1/account/webhook_settings

Returns

[Swagger:response:table:getWebhookSettings]

Update webhook settings

[Swagger:request:curl:updateWebhookSettingsJson]

The above command returns JSON structured like this

[Swagger:response:json:updateWebhookSettingsJson]

Update webhook settings. Webhook secret is left unchanged and must separately be re-generated. See below.

HTTP Request

PUT https://api.reepay.com/v1/account/webhook_settings

[Swagger:request:table:updateWebhookSettingsJson]

Returns

Returns the updated WebhookSettings

Generate new webhook secret

[Swagger:request:curl:generateWebhookSecret]

The above command returns JSON structured like this

[Swagger:response:json:generateWebhookSecret]

Generate a new webhook secret.

HTTP Request

POST https://api.reepay.com/v1/account/webhook_settings/secret

Returns

Returns the WebhookSettings object, containing the new secret.

Get Invoice Configuration

[Swagger:request:curl:getInvoiceConfiguration]

The above command returns JSON structured like this

[Swagger:response:json:getInvoiceConfiguration]

Get the invoice configuration for account.

HTTP Request

GET https://api.reepay.com/v1/invoice_configuration

Returns

Returns the InvoiceConfiguration.

Create or update Invoice Configuration

[Swagger:request:curl:updateInvoiceConfiguration]

The above command returns JSON structured like this

[Swagger:response:json:updateInvoiceConfiguration]

Create or update invoice account settings.

HTTP Request

POST https://api.reepay.com/v1/invoice_configuration

[Swagger:request:table:updateInvoiceConfiguration]

Get Invoice Sequence Configuration

[Swagger:request:curl:getInvoiceSequenceConfiguration]

The above command returns JSON structured like this

[Swagger:response:json:getInvoiceSequenceConfiguration]

Get the invoice sequence configuration for account.

HTTP Request

GET https://api.reepay.com/v1/invoice_configuration/sequence

Returns

Returns the InvoiceSequenceConfiguration.

Create or update Invoice Sequence Configuration

[Swagger:request:curl:createInvoiceSequenceConfiguration]

The above command returns JSON structured like this

[Swagger:response:json:createInvoiceSequenceConfiguration]

Create or update invoice account settings.

HTTP Request

POST https://api.reepay.com/v1/invoice_configuration/sequence

[Swagger:request:table:createInvoiceSequenceConfiguration]

Organisation

Organisation resource for managing organisation settings.

The Organisation object

[Swagger:definition:json:Organisation]

[Swagger:definition:table:Organisation]

Get organisation

[Swagger:request:curl:getOrganisation]

The above command returns JSON structured like this

[Swagger:response:json:getOrganisation]

Get organisation for authenticated account.

HTTP Request

GET https://api.reepay.com/v1/organisation

Return

Returns an Organisation object.

Update organisation

[Swagger:request:curl:update]

The above command returns JSON structured like this

[Swagger:response:json:update]

Update organisation.

HTTP Request

PUT https://api.reepay.com/v1/organisation

[Swagger:request:table:update]

Return

Returns an Organisation object.

Plan

A subscription plan defines subscription product information, subscription terms, and when and how much to charge for a subscription. An unlimited number of plans can be defined for an account.

Subscription plans are versioned so changes (superseding) results in a new version of the plan. It can be chosen to either let subscriptions stay on the old version of the plan, or to change for all subscriptions using the plan.

The Plan object

[Swagger:definition:json:Plan]

[Swagger:definition:table:Plan]

Get list of plans

[Swagger:request:curl:getPlanList]

The above command returns JSON structured like this

[Swagger:response:json:getPlanList]

Get list of plans. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/plan

Query Parameters

[Swagger:request:table:getPlanList]

Return

Returns a list response object containing Plans in the content array.

Create plan

[Swagger:request:curl:createPlanJson]

The above command returns JSON structured like this

[Swagger:response:json:createPlanJson]

You can create plans easily via the plan management page of the Reepay dashboard. Plan creation is also accessible via the API if you need to create plans from you own system.

HTTP Request

POST https://api.reepay.com/v1/plan

[Swagger:request:table:createPlanJson]

Return

Returns a Plan object.

Get list of plan versions

[Swagger:request:curl:getPlans]

The above command returns JSON structured like this

[Swagger:response:json:getPlans]

You can get a list of all version of a plan. If you Supersede a plan to update things like amount, then Reepay will generate a new version of the plan. You can keep current subscriptions on the old plan version.

Using this you can get a full list of all versions of a plan.

HTTP Request

GET https://api.reepay.com/v1/plan/{handle}

[Swagger:request:table:getPlans]

Return

Returns an array of Plan objects.

Supersede plan

[Swagger:request:curl:supersedePlanJson]

The above command returns JSON structured like this

[Swagger:response:json:supersedePlanJson]

If you want to update a plans amount and information that has a big effect on the subscriptions you must supersede the old plan, which means Reepay will create a new version of the plan. For this you use “supersede plan” instead of “update plan”.

Beside the normal plan features you must decide what will happen with the current subscriptions that uses the plan. For this you use supersede_mode, that can be set to the following modes:

Mode Description
no_sub_update Using this all subscriptions will still use the old version of the plan.
scheduled_sub_update This will update all subscriptions to use the new version after the current billing period ends.

HTTP Request

POST https://api.reepay.com/v1/plan/{handle}

[Swagger:request:table:supersedePlanJson]

Return

Returns a Plan object.

Update plan

[Swagger:request:curl:updatePlanJson]

The above command returns JSON structured like this

[Swagger:response:json:updatePlanJson]

Use this to update a plan. I you want to update major things like amount, please use Supersede instead.

HTTP Request

PUT https://api.reepay.com/v1/plan/{handle}

[Swagger:request:table:updatePlanJson]

Return

Returns a Plan object.

Delete plan

[Swagger:request:curl:deletePlan]

The above command returns JSON structured like this

[Swagger:response:json:deletePlan]

You can delete plans via the plan management page of the Reepay dashboard. However, deleting a plan does not affect any current subscribers to the plan; it merely means that new subscribers can’t be added to that plan. You can also delete plans via the API.

HTTP Request

DELETE https://api.reepay.com/v1/plan/{handle}

[Swagger:request:table:deletePlan]

Return

Returns a Plan object.

Undelete plan

[Swagger:request:curl:unDeletePlan]

The above command returns JSON structured like this

[Swagger:response:json:unDeletePlan]

Undelete deleted plan

HTTP Request

POST https://api.reepay.com/v1/plan/{handle}/undelete

[Swagger:request:table:unDeletePlan]

Return

Returns a Plan object.

Get plan

[Swagger:request:curl:getCurrentPlan]

The above command returns JSON structured like this

[Swagger:response:json:getCurrentPlan]

Retrieves current version of the plan with the given handle.

HTTP Request

GET https://api.reepay.com/v1/plan/{handle}/current

[Swagger:request:table:getCurrentPlan]

Return

Returns a Plan object.

Get plan version

[Swagger:request:curl:getPlan]

The above command returns JSON structured like this

[Swagger:response:json:getPlan]

Retrieves a version of the plan with the given handle.

HTTP Request

GET https://api.reepay.com/v1/plan/{handle}/{version}

[Swagger:request:table:getPlan]

Return

Returns a Plan object.

Dunning plan

For an account a number of dunning plans can be configured. An account must have at least one dunning plan. One of the dunning plans must be defined as the default dunning plan.

A dunning plan is a plan for the dunning process an invoice goes into if the settlement of an invoice fails. A dunning plan consists of a schedule as a list of intervals in days, and a final action for the subscription if the dunning process fails. The final action is either to do nothing, or to expire the subscription.

The dunning process proceeds as follows:

For a schedule with only one interval a single notification is sent followed by a wait and then the final action is taken if the invoice is not settled before the interval end. If an empty schedule is used, no notification is sent and the final action is taken immediately.

The Dunning plan object

[Swagger:definition:json:DunningPlan]

[Swagger:definition:table:DunningPlan]

Get list of dunning plans

[Swagger:request:curl:getDunningPlans]

The above command returns JSON structured like this

[Swagger:response:json:getDunningPlans]

Get list of dunning plans

HTTP Request

GET https://api.reepay.com/v1/dunning_plan

Return

Returns an array of Dunning Plan objects.

Create dunning plan

[Swagger:request:curl:createDunningPlanJson]

The above command returns JSON structured like this

[Swagger:response:json:createDunningPlanJson]

Create a new dunning plan.

HTTP Request

POST https://api.reepay.com/v1/dunning_plan

[Swagger:request:table:createDunningPlanJson]

Return

Returns a Dunning Plan object.

Get dunning plan

[Swagger:request:curl:getDunningPlan]

The above command returns JSON structured like this

[Swagger:response:json:getDunningPlan]

Get dunning plan by handle.

HTTP Request

GET https://api.reepay.com/v1/dunning_plan/{handle}

[Swagger:request:table:getDunningPlan]

Return

Returns a Dunning Plan object.

Update dunning plan

[Swagger:request:curl:updateJson]

The above command returns JSON structured like this

[Swagger:response:json:updateJson]

Update dunning plan. If currently default plan is made non-default, the oldest plan will be made new default.

HTTP Request

PUT https://api.reepay.com/v1/dunning_plan/{handle}

[Swagger:request:table:updateJson]

Return

Returns a Dunning Plan object.

Delete dunning plan

[Swagger:request:curl:deleteDunningPlan]

The above command returns JSON structured like this

[Swagger:response:json:deleteDunningPlan]

Delete dunning plan. A dunning plan can only be deleted if no subscription plans use the dunning plan, and only if the dunning plan is not the only remaining plan. If the deleted plan is default, the oldest plan will be made new default.

HTTP Request

DELETE https://api.reepay.com/v1/dunning_plan/{handle}

[Swagger:request:table:deleteDunningPlan]

Return

Returns a Dunning Plan object.

Customer

The customer object is core to managing your customers inside of Reepay. The customer object stores the entire Reepay history of your customer and acts as the entry point for working with a customer’s billing information, subscription data, invoices and more.

The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers and also manage notes and payment methods.

The Customer object

[Swagger:definition:json:Customer]

[Swagger:definition:table:Customer]

Get list of customers

[Swagger:request:curl:getCustomerList]

The above command returns JSON structured like this

[Swagger:response:json:getCustomerList]

Get list of customers. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/customer

Query Parameters

[Swagger:request:table:getCustomerList]

Return

Returns a list response object containing Customers in the content array.

Examples

Get customer with email

GET https://api.reepay.com/v1/list/customer?email=mail@example.com

Get customers with John contained in name

GET https://api.reepay.com/v1/list/customer?name=John

Create customer

[Swagger:request:curl:createCustomerJson]

The above command returns JSON structured like this

[Swagger:response:json:createCustomerJson]

HTTP Request

POST https://api.reepay.com/v1/customer

[Swagger:request:table:createCustomerJson]

Return

Returns a Customer object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
11 400 Duplicate handled - already used

Get customer

[Swagger:request:curl:getCustomer]

The above command returns JSON structured like this

[Swagger:response:json:getCustomer]

Retrieves the details of an existing customer. You need only supply the unique customer handle you defined upon creation.

HTTP Request

GET https://api.reepay.com/v1/customer/{handle}

[Swagger:request:table:getCustomer]

Return

Returns a Customer object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found

Update customer

[Swagger:request:curl:updateCustomerJson]

The above command returns JSON structured like this

[Swagger:response:json:updateCustomerJson]

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be deleted.

HTTP Request

PUT https://api.reepay.com/v1/customer/{handle}

[Swagger:request:table:updateCustomerJson]

Return

Returns a Customer object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found
71 400 Customer is deleted

Delete customer

[Swagger:request:curl:deleteCustomer]

The above command returns JSON structured like this

[Swagger:response:json:deleteCustomer]

A customer can be soft-deleted meaning that the customer resource remains with a status deleted, and all sensitive data is removed from the resource. All related resources like subscriptions and invoices are not deleted. A deleted customer will not appear in the customer list. The customer handle is not changed so it cannot be re-used.

A customer can only be deleted if it has none or only expired subscriptions, and no pending or dunning invoices.

HTTP Request

DELETE https://api.reepay.com/v1/customer/{handle}

[Swagger:request:table:deleteCustomer]

Return

Returns a Customer object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found
71 400 Customer is deleted
32 400 Customer has non-expired subscriptions, these must be handled first
33 400  Customer has pending and/or dunning invoices, these must be handled first

Create invoice for customer

[Swagger:request:curl:createCustomerInvoice]

The above command returns JSON structured like this

[Swagger:response:json:createCustomerInvoice]

A one-time invoice can be created on demand for a customer by providing a number of order lines. The invoice can later be settled using a customer payment method or using a manual transfer e.g. bank transfer. The creation and settlement can also be done in one operation by either supplying a settle payment method or a manual transfer to the create operation. The result of the creation is an invoice with state pending if not settled directly, or state settled or failed depending on the result of the immediate settle attempt.

HTTP Request

POST https://api.reepay.com/v1/customer/{handle}/invoice

[Swagger:request:table:createCustomerInvoice]

Returns

Returns an Invoice object for the created invoice.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found
11 400 Duplicate handle provided
76  400 Payment method not provided and settle requested
40 404  Payment method provided not found

Get customer notes

[Swagger:request:curl:getCustomerNotes]

The above command returns JSON structured like this

[Swagger:response:json:getCustomerNotes]

Your team can leave notes on an customer to add context, e.g. the reason for a refund, customer requests, and/or complaints. These notes are internal and not exposed to your customers.

Use this to get a list of notes for a specific customer.

HTTP Request

GET https://api.reepay.com/v1/customer/{handle}/note

[Swagger:request:table:getCustomerNotes]

Return

Returns an array of Customer Note objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found

Create customer note

[Swagger:request:curl:createCustomerNoteJson]

The above command returns JSON structured like this

[Swagger:response:json:createCustomerNoteJson]

Create a note for a customer. Specify who has created the note by dictate user_name and user_email. The user information is not a part of Reepay’s user concept but can be your intern user information.

HTTP Request

POST https://api.reepay.com/v1/customer/{handle}/note

[Swagger:request:table:createCustomerNoteJson]

Return

Returns a Customer Note object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found
71 400 Customer is deleted
17 404  Provided user not found

Payment Method

The Payment Method resource provides operations for payment methods saved for recurring use. Saved payment methods are tied to customers and are usually created using Reepat Checkout recurring and subscription sessions.

The Payment Method object

[Swagger:definition:json:PaymentMethodV2]

[Swagger:definition:table:PaymentMethodV2]

Get list of payment methods

[Swagger:request:curl:getPaymentMethodList]

The above command returns JSON structured like this

[Swagger:response:json:getPaymentMethodList]

Get list of payment methods. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/payment_method

Query Parameters

[Swagger:request:table:getPaymentMethodList]

Return

Returns a list response object containing PaymentMethods in the content array.

Examples

Get saved card payment methods for customer cust-0001 created in 2022

GET https://api.reepay.com/v1/list/payment_method?from=2022-01-01&customer=cust-0001&payment_type=card

Get payment method

[Swagger:request:curl:getPaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:getPaymentMethodV2]

Get payment method by id

HTTP Request

GET https://api.reepay.com/v1/payment_method/{id}

[Swagger:request:table:getPaymentMethodV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found

Add payment method

[Swagger:request:curl:addPaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:addPaymentMethodV2]

Add a payment method using a source, e.g. one-time card token ct_.... An existing customer can be referenced or a new customer can be created in an atomic operation.

HTTP Request

POST https://api.reepay.com/v1/payment_method

[Swagger:request:table:addPaymentMethodV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found
34 400 Invalid card token provided as source
40 404 Payment method not found
103 400 Card token already used
104 400 Card token has expired

Delete payment method

[Swagger:request:curl:deletePaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:deletePaymentMethodV2]

A payment method can be deleted. An deleted payment method will not be used to pay invoices and will not appear in customer payment method lists. For payment methods like MobilePay Subscriptions the subscription agreement will be cancelled.

HTTP Request

DELETE https://api.reepay.com/v1/payment_method/{id}

[Swagger:request:table:deletePaymentMethodV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found

Inactivate payment method

[Swagger:request:curl:inactivatePaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:inactivatePaymentMethodV2]

A payment method can be inactivated. An inactivated payment method will not be used to pay invoices.

HTTP Request

POST https://api.reepay.com/v1/payment_method/{id}/inactivate

[Swagger:request:table:inactivatePaymentMethodV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found
42  400  Payment method not active

Activate payment method

[Swagger:request:curl:activatePaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:activatePaymentMethodV2]

A previously inactivated payment method can be re-activated.

HTTP Request

POST https://api.reepay.com/v1/payment_method/{id}/activate

[Swagger:request:table:activatePaymentMethodV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found
41 400 Payment method not inactive

Reactivate failed card

[Swagger:request:curl:reactivateCardV2]

The above command returns JSON structured like this

[Swagger:response:json:reactivateCardV2]

A failed card can be reactivated in the case of wrong marking as failed. The card will be available to use as payment method for charges, on on-demand invoices and subscriptions. If already used on subscription with pending or dunning invoices the card will be retried as payment method.

HTTP Request

POST https://api.reepay.com/v1/payment_method/{id}/card_reactivate

[Swagger:request:table:reactivateCardV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
19 404  Card not found

Copy card payment method

[Swagger:request:curl:copyCardPaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:copyCardPaymentMethodV2]

Copy an existing card payment method to customer. An existing customer can be referenced or a new customer can be created in an atomic operation.

HTTP Request

POST https://api.reepay.com/v1/payment_method/{id}/card_copy

[Swagger:request:table:copyCardPaymentMethodV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
7 403 Unauthorized. Returned if card does not belong to account, and there is no link established between accounts.
9 404 Customer not found
40 404 Payment method not found
55 404 Agreement could not be found

Move card payment method

[Swagger:request:curl:moveCardPaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:moveCardPaymentMethodV2]

A saved card is tied to a card acquiring agreement, so all Merchant-Initiated Transcations (MIT) for the card will be done on this agreement. A card can be moved to another agreement using the move card operation. The agreement selection when moving card is as for a new card addition. The agreement card types and supported currencies must match. The following can be used to control agreement selection:

  1. Disbale/delete existing agreement and create new active agreement. The new active agreement will be used if card type match.
  2. Provide currency and/or card type to guide agreement selection. Notice that card type is only relevant in co-branded card scenarios. E.g. to force Visa-Dankort on Dankort or Visa agreement.
  3. Explicitly define the agreement to which the card should be moved.

HTTP Request

POST https://api.reepay.com/v1/payment_method/{id}/card_move

[Swagger:request:table:moveCardPaymentMethodV2]

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found
55 404 Agreement could not be found

Get payment method details

[Swagger:request:curl:getPaymentMethodDetailsV2]

The above command returns JSON structured like this

[Swagger:response:json:getPaymentMethodDetailsV2]

Get payment gateway specific information for card.

HTTP Request

GET https://api.reepay.com/v1/payment_method/{id}/details

[Swagger:request:table:getPaymentMethodDetailsV2]

Return

Returns a JSON object with acquirer specific key/value details for the payment method.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found

Card verification

[Swagger:request:curl:cardVerification]

The above command returns JSON structured like this

[Swagger:response:json:cardVerification]

Some card acquirers support a card verification operation. The operation checks the validity of a stored card without making an actual authorization on the card. That is, the check will not be visible to the cardholder on their bank statement. Currently this operation is only supported for acqurier Nets, Swedbank, Bambora and Valitor. Notice that this operation is subject to charges. See reepay.com for the current pricing or contact support@reepay.com for more information on pricing and how to utilize this service.

To test the operation with the test acquirer, specific CVV codes can be used to trigger erros:

CVV State Error
901 soft_declined insuffcient_funds
902 hard_declined declined_by_acquirer
903 processing_error acquirer_error

HTTP Request

POST https://api.reepay.com/v1/payment_method/{id}/card/verify

[Swagger:request:table:cardVerification]

Return

Returns a CardVerification object.

[Swagger:response:table:cardVerification]

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found
18 404 Card not found
138 400 Card verification not supported by the current acquirer agreements

Card enrollment

[Swagger:request:curl:enrollCardPaymentMethodV2]

The above command returns JSON structured like this

[Swagger:response:json:enrollCardPaymentMethodV2]

Enroll an existing card to EMV tokenization. Currently only supported for Visa card types. After the card is enrolled the payment type is updated to emv_token. The card can then be used for EMV tokenization payments and card updates will be received from the card scheme.

HTTP Request

`POST https://api.reepay.com/v1/payment_method/{id}/card_enroll

Return

Returns a PaymentMethod object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found
34 400 Enrollment not supported - declined by acquirer or tokenization not activated/supported

Subscription

Subscriptions tie customers to plans and are responsible for billing according to the billing schedule defined on the plan. A customer can have multiple subscriptions. A customer subscribing to a plan is the result of a subscription sign up

For a simple example of how to use the subscription resource see our subscription example here.

The Subscription object

[Swagger:definition:json:Subscription]

[Swagger:definition:table:Subscription]

Get list of subscriptions

[Swagger:request:curl:getSubscriptionList]

The above command returns JSON structured like this

[Swagger:response:json:getSubscriptionList]

Get list of subscriptions. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/subscription

Query Parameters

[Swagger:request:table:getSubscriptionList]

Returns

Returns a list response object containing Subscriptions in the content array.

Examples

A common query is to get all active subscriptions for a customer. This can be used to authorize a user for a certain action that requires a subscription.

GET https://api.reepay.com/v1/list/subscriptiopn?customer=cust-007&state=active

All active subscriptions with a given plan can be fetched like this.

GET https://api.reepay.com/v1/list/subscriptiopn?plan=gold&state=active

All subscriptions activated after a certian date and time

GET https://api.reepay.com/v1/list/invoice?range=activated&from=2022-03-01&to=2022-04-01

Get subscription

[Swagger:request:curl:getSubscription]

HTTP Request

GET https://api.reepay.com/v1/subscription/{handle}

[Swagger:request:table:getSubscription]

Returns

Returns the requested Subscription object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found

Create subscription

[Swagger:request:curl:createSubscriptionJson]

Create a subscription (and optionally customer). Payment information can be obtained in one of the following ways:

The parameter start_date is optional and indicates when the subscription is eligible to begin the first billing period. Whether the first billing period i starting at start_date depends on the schedule type on the plan for the subscription. If a fixed day schedule type is used, the first billing period will start on the first fixed day after start_date.

A subscription creation can be made conditional on a successful payment of the first invoice. See the parameter conditional_create. This will require a signup method of source, and the subscription must be eligible for billing for the first period right away.

When creating a subscription either a reference to an existing customer must be provided, or a customer can be created in the same operation using the parameter create_customer. The operation is atomic, so if subscription create fails, no customer will be created.

An example of how to use the create subscription API operation can be fore here.

To add subscription add-ons when creating a list of CreateSubscriptionAddOn objects can be provided in parameter add_ons. An example on the use of add-ons can be found here.

Additional costs can be added to a subscription at creation time by providing a list of CreateSubscriptionAdditionalCost objects in parameter additional_costs.

HTTP Request

POST https://api.reepay.com/v1/subscription

[Swagger:request:table:createSubscriptionJson]

Returns

Returns the created Subscription object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
9 404 Customer not found
10 404 Subscription plan provided not found
11 400 Duplicate handle - subscription handle, additional cost handle or subscription add-on handle already used
14 400 End date must be in the future
19 404 Customer card provided as source but cannot be found
34 400 Invalid card token provided as source
37  400 Start date if provided cannot be more than one period in the past, e.g. one month.
75 400 Subscription not eligible for invoice. This error is returned if the conditional_create parameter is set to true, but the subscription does not have a plan resulting in an invoice right away. This is the case for subscription plans with fixed day billing. E.g. on the first of every month.
83 404  Discount not found
85  400 Multiple discounts not allowed
86 404 Coupon not found or not eligible
87 400 Coupon already used
103 400 Card token already used
104 400 Card token has expired
110 400 Unknown or missing source argument
111 400 Source not allowed for signup method
113 404 Add-on not found
114 400 Add-on already added or multiple occurences of same add-on in request without explicit unique subscription add-on handle
115  400  Add-on quantity not allowed for on-off add-on type
116 400 Add-on not eligible for subscription plan

Create subscription preview

[Swagger:request:curl:previewSubscription]

The above command returns JSON structured like this

[Swagger:response:json:previewSubscription]

A subscription preview can be created by providing the same arguments as for a normal subscription create. The arguments signup_method and source are ignored as no real subscription is created. The preview returned is not stored but it shows how the created subscription would look like and also returns a list of invoices that would be created.

HTTP Request

POST https://api.reepay.com/v1/subscription/preview

[Swagger:request:table:previewSubscription]

Returns

Returns a PreparedSubscription object which is a Subscription object with additional list of invoices.

Errors

The operation can generate the same errors as a subscription create.

Cancel subscription

[Swagger:request:curl:cancelSubscription]

An active subscription can be cancelled. When the subscription will expire is determined by possible notice and fixation period defined for the plan, or optional overriding notice period defined in the cancel request. By default the subscription will expire at the end of the current billing period. Cancelling a subscription in trial will always result in an expire at the end of the trial period.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/cancel

[Swagger:request:table:cancelSubscription]

Returns

Returns the cancelled Subscription object with is_cancelled=true and the parameter expires set to when the subscription will expire.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
13 400 Subscription expired, must be active
95 400 Subscription on-hold, must be active
22 400 Subscription already cancelled
93 400 Cannot expire in current period. A custom expires at has been provided that is in the current period.

Uncancel subscription

[Swagger:request:curl:uncancel]

A cancelled subscription can be made active again, not expiring it at the end of current billing period.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/uncancel

[Swagger:request:table:uncancel]

Returns

Returns the Subscription object, which has been uncancelled.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
13 400 Subscription expired
95 400 Subscription on-hold
94  400  Cannot uncancel because subscription is in a final partial period. Partial last periods are created when a fixed expire date was defined for the cancel.

Expire subscription

[Swagger:request:curl:expire]

Expire the subscription instantly. The operation will fail if the subscription has pending or dunning invoices. Handle these separately, e.g. by cancelling all dunning and pending. Expire can be given an optional argument describing how to compensate for the current period if already paid for with settled invoice.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/expire

[Swagger:request:table:expire]

Returns

Returns the Subscription object, with state expired.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
13 400 Subscription already expired
63 400 Subscription has pending or dunning invoices, these needs to be handled first
64 400 Refund compensation is used but the current billing period invoice is not in required state settled
65 400 Refund compensation is used but the refund amount exceeds the refundable amount on the current billing period invoice. The refundable amount is the setlled invoice amount minus already refunded and credited amounts.
81 400 Refund compensation is not allowed for asynchronous refund payment method
66 500 The refund compensation failed because of error at the acquirer. See transaction_error See transaction errors.

Prepare subscription

[Swagger:request:curl:prepareSubscription]

Instead of creating a subscription directly, it can be done in a two step process:

  1. Prepare pending subscription. Same as create subscription except for not requiring payment method information.
  2. Activate subscription. Payment method step of create subscription.

A prepared subscription will have state pending and potential invoices will have state created. A prepared subscription will give all details of the subscription including invoices to be paid right away. This can be presented to the customer in an accept phase. The subscription can subsequently be activated with the activate operation.

A subscription in state pending can be deleted completely with the delete pending subscription operation.

HTTP Request

POST https://api.reepay.com/v1/subscription/prepare

[Swagger:request:table:prepareSubscription]

Returns

Returns a PreparedSubscription object which is a Subscription object with additional list of invoices.

Errors

For errors see Create Subscription.

Activate subscription

[Swagger:request:curl:activate]

Step 2 of a prepare -> activate subscription creation process.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/activate

[Swagger:request:table:activate]

Returns

Returns the Subscription object, with state active.

Errors

For errors see Create Subscription.

Delete pending subscription

[Swagger:request:curl:deletePending]

A subscription in state pending can be deleted with the two exceptions below:

  1. If the subscription has invoices that are not only in state created. E.g. a failed invoice.
  2. If the subscription has a created invoice with transactions. If the created invoice has transactions an actual payment has been attempted in connection with signup. This means that a transaction has been attempted with payment method. Deleting the subscription would require to delete invoice and transaction removing the trace of the payment attempt, disallowing to subsequently find the transcation registered with acquirer and issuer in Reepay.

HTTP Request

DELETE https://api.reepay.com/v1/subscription/{handle}

[Swagger:request:table:deletePending]

Returns

Returns HTTP response code 204 and no content on success.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
119 400 Subscription not in state pending
125 400 Subscription has pending payment method
82 400 Invoice not in state created
30 400 Invoice has active transactions

Change subscription

Plan, add-ons, amount and plan quantity can be changed either immediately or at next renewal. Typically upgrades will be done immediate and downgrades at next renewal.

A pending change at renewal will be reflected in the pending_change object on the subscription. An immediate change will cancel the pending change and a new change at renewal will replace the previous one.

To change subscription add-ons a list of subscription add-on handles to remove can be provided and a list of CreateSubscriptionAddOn objects can be provided to attach new subscription add-ons. A subscription add-on cannot be updated, but instead a remove and an attach of the same add-on can be performed. To only change add-ons immediately without any compensation or new billing, a change with add-on parameters and compensation_method=none and billing=none can be performed. An example on the use of add-ons can be found here.

[Swagger:request:curl:changeSubscription]

HTTP Request

PUT https://api.reepay.com/v1/subscription/{handle}

[Swagger:request:table:changeSubscription]

Returns

Returns a Subscription object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
11 400 Duplicate handle - Subscription add-on handle already used or multiple occurences of same handle in request
13 400 Subscription expired, must be actice or on-hold (only if not immedidate change)
95 400 Subscription on-hold and immediate change requested
64 400 Refund compensation is used but the current billing period invoice is not in required state settled
65 400 Refund compensation is used but the refund amount exceeds the refundable amount on the current billing period invoice. The refundable amount is the setlled invoice amount minus already refunded and credited amounts.
82 400 Credit compensation is used but the current billing period invoice is not in required state pending, dunning or settled
120 400 Credit compensation is used but credit amount exceeds the creditable amount on the current billing period invoice. The creditable amount is the invoice amount minus already refunded and credited amount.
22 400 Subscription cancelled
10 404 Subscription plan to change to not found
117  404  Subscription add-on to remove not found
113  404 Add-on to add not found
114 400 Add-on already added to subscription or multiple occurences of same add-on in request without explicit unique subscription add-on handle
11 400 Duplicate subscription add-on handle
116  400 Add-on to add not eligible for the subscription plan
115 400 Quantity provided for an on-off add-on
37 400 A new start date has been provided that is too far in the past
66 500 The refund compensation failed because of error at the acquirer. See transaction_error See transaction errors.

Change subscription preview

A subscription change can be tried out by creating a subscription change preview. The preview does not perform any actual change but sums up what would happen if the change request was performed.

[Swagger:request:curl:previewChangeSubscription]

HTTP Request

PUT https://api.reepay.com/v1/subscription/{handle}/preview

[Swagger:request:table:previewChangeSubscription]

Returns

Returns a ChangedSubscription object which is the Subscription object after the change with additional parameter SubscriptionChangeJournal describing potential compensation and new billing.

Errors

The operation can generate the same errors as for a normal change operation.

Change next renewal date

[Swagger:request:curl:changeNextPeriodStartJson]

The start of the next billing period can be adjusted. The new date is required to be in the future. Notice that the effect of using this functionality is different if a fixed day schedule type is used. If such is used the actual next billing period start will be the first fixed day after the given date.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/change_next_period_start

[Swagger:request:table:changeNextPeriodStartJson]

Returns

Returns the Subscription object, which just had its renewal date changed.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
13 400 Subscription expired, must be active
95 400 Subscription on-hold, must be active
22 400 Subscription cancelled with a specific expire date. In this case the next renewal date cannot be changed
14 400 The provided date is not in the future

Subscription on hold

[Swagger:request:curl:onHold]

Put subscription instantly on hold. Subscription must be active and not in trial. A subscription on hold can later be reactivated. An optional argument can be given describing how to compensate for the current period if already paid for with settled invoice. If compensation is used the subscription must have a settled invoice for the current billing period.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/on_hold

[Swagger:request:table:onHold]

Returns

Returns the Subscription object, with state on_hold.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
13 400 Subscription expired, must be active
95 400 Subscription on-hold, must be active
96 400 Subscription is in trial, not allowed to put on hold
64 400 Refund compensation is used but the current billing period invoice is not in required state settled
65 400 Refund compensation is used but the refund amount exceeds the refundable amount on the current billing period invoice. The refundable amount is the setlled invoice amount minus already refunded and credited amounts.
82 400 Credit compensation is used but the current billing period invoice is not in required state pending, dunning or settled
120 400 Credit compensation is used but credit amount exceeds the creditable amount on the current billing period invoice. The creditable amount is the invoice amount minus already refunded and credited amount.
81 400 Refund compensation is not allowed for asynchronous refund payment method
66 500 The refund compensation failed because of error at the acquirer. See transaction_error See transaction errors.

Reactivate subscription

[Swagger:request:curl:reactivateSubscription]

A subscription on hold can be reactivated to active state. An optional start date can be given to control from when the subscription is eligible to start first billing period after on hold. The plan handling of potential partial periods can be overridden using an optional argument.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/reactivate

[Swagger:request:table:reactivateSubscription]

Returns

Returns the Subscription object, with state active.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
97 400 Subscription not on-hold
37 400 Provided start date cannot be before the on-hold date

Get payment methods

[Swagger:request:curl:getSubscriptionPaymentMethod]

The above command returns JSON structured like this

[Swagger:response:json:getSubscriptionPaymentMethod]

Get payment methods attached to subscription (currently maximum one allowed).

HTTP Request

GET https://api.reepay.com/v1/subscription/{handle}/pm

[Swagger:request:table:getSubscriptionPaymentMethod]

Returns

Returns a list of PaymentMethod objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found

Remove all payment methods

[Swagger:request:curl:removeAllSubscriptionPaymentMethods]

The above command returns JSON structured like this

[Swagger:response:json:removeAllSubscriptionPaymentMethods]

Remove all payment methods from subscription. If the subscription has an existing tightly coupled payment method, e.g. MobilePay Subcriptions agreement, the subscription agreement will be cancelled and the payment method will be deleted.

HTTP Request

DELETE https://api.reepay.com/v1/subscription/{handle}/pm

[Swagger:request:table:removeAllSubscriptionPaymentMethods]

Returns

Returns a list of PaymentMethod objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found

Set payment method

[Swagger:request:curl:setSubscriptionPaymentMethod]

The above command returns JSON structured like this

[Swagger:response:json:setSubscriptionPaymentMethod]

Set payment method for the subscription, either by an existing customer payment method ca_... or a customer payment method obtained with Reepay Checkout.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/pm

[Swagger:request:table:setSubscriptionPaymentMethod]

Returns

Returns a list of PaymentMethod objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
40 404 Payment method reference provided not found
34 400 Invalid card token provided as source
103 400 Card token already used
104 400 Card token has expired
110 400 Unknown or missing source argument

Remove payment method

[Swagger:request:curl:removeSubscriptionPaymentMethod]

The above command returns JSON structured like this

[Swagger:response:json:removeSubscriptionPaymentMethod]

Remove a specific payment method from subscription. For tightly coupled payment methods, e.g. MobilePay Subcriptions, the subscription agreement will be cancelled and the payment method will be deleted.

HTTP Request

DELETE https://api.reepay.com/v1/subscription/{handle}/pm/{method_id}

[Swagger:request:table:removeSubscriptionPaymentMethod]

Returns

Returns a list of PaymentMethod objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
40 404 Payment method reference provided not found

Create invoice for subscription

[Swagger:request:curl:createSubscriptionInvoice]

The above command returns JSON structured like this

[Swagger:response:json:createSubscriptionInvoice]

A one-time invoice can be created on demand for a subscription. It is configurable in the request where the order lines for the invoice should come from. The following are possible:

By default the invoice is generated and tried settled using the payment method attached to the subscription. If it cannot be settled it will enter dunning management as automatically generated subscription invoices. It is also possible to let the outcome of a creation be either a settled or a failed invoice by using the instant parameter. This can be used for subscription invoices not relevant for possible dunning management.

Optionally either an offline manual transfer or a settle with an alternative payment method can be given for the invoice creation. The manual transfer will always settle the invoice. If a settle using an alternative payment method fails, the invoice will left pending if instant is not used, and failed otherwise.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/invoice

[Swagger:request:table:createSubscriptionInvoice]

Returns

Returns an Invoice object for the created invoice.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
13 400 Subscription expired
95 400 Subscription on-hold
54 400 The request results in an invoice with no order lines
1  400  Due argument was given for an instant invoice request
76  400 Payment method not provided and settle requested
40 404  Payment method provided not found

Get subscription add-ons

[Swagger:request:curl:getSubscriptionAddOns]

The above command returns JSON structured like this

[Swagger:response:json:getSubscriptionAddOns]

Get subscription add-ons attached to subscription.

HTTP Request

GET https://api.reepay.com/v1/subscription/{handle}/add_on

[Swagger:request:table:getSubscriptionAddOns]

Return

Returns an array of Subscription Add-On objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found

Get subscription add-on

[Swagger:request:curl:getSubscriptionAddOn]

The above command returns JSON structured like this

[Swagger:response:json:getSubscriptionAddOn]

Get subscription add-on attached to subscription.

HTTP Request

GET https://api.reepay.com/v1/subscription/{handle}/add_on/{saHandle}

[Swagger:request:table:getSubscriptionAddOn]

Return

Returns a Subscription Add-On object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
117 404 Subscription add-on not found

Get subscription discounts

[Swagger:request:curl:getSubscriptionDiscounts]

The above command returns JSON structured like this

[Swagger:response:json:getSubscriptionDiscounts]

Get subscription discounts attached to subscription. Active, and deleted that has been applied to one or more invoices, will be returned.

HTTP Request

GET https://api.reepay.com/v1/subscription/{handle}/discount

[Swagger:request:table:getSubscriptionDiscounts]

Return

Returns an array of SubscriptionDiscount objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found

Get subscription discount

[Swagger:request:curl:getSubscriptionDiscount]

The above command returns JSON structured like this

[Swagger:response:json:getSubscriptionDiscount]

Get subscription discount attached to subscription.

HTTP Request

GET https://api.reepay.com/v1/subscription/{handle}/discount/{sdHandle}

[Swagger:request:table:getSubscriptionDiscount]

Return

Returns a SubscriptionDiscount object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
84 404 Subscription discount not found

Add subscription discount

[Swagger:request:curl:createSubscriptionDiscount]

The above command returns JSON structured like this

[Swagger:response:json:createSubscriptionDiscount]

Add a subscription discount using discount as template. Only discount argument is mandatory the rest of the arguments can be used to override the settings on the discount.

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/discount

[Swagger:request:table:createSubscriptionDiscount]

Return

Returns a SubscriptionDiscount object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
83 404 Discount not found
11 400 Duplicate subscription discount handle given
85  400  Multiple discounts not allowed. Can be changed in discount settings

Delete subscription discount

[Swagger:request:curl:deleteSubscriptionDiscount]

The above command returns JSON structured like this

[Swagger:response:json:deleteSubscriptionDiscount]

Remove a subscription discount from a subscription.

HTTP Request

DELETE https://api.reepay.com/v1/subscription/{handle}/discount/{sdHandle}

[Swagger:request:table:deleteSubscriptionDiscount]

Return

Returns a SubscriptionDiscount object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
84 404 Subscription discount not found

Redeem coupon code

Redeem a coupon code for subscription.

[Swagger:request:curl:redeemCouponCode]

The above command returns JSON structured like this

[Swagger:response:json:redeemCouponCode]

HTTP Request

POST https://api.reepay.com/v1/subscription/{handle}/coupon

[Swagger:request:table:redeemCouponCode]

Return

Returns a CouponRedemption object consisting of redeemed Coupon and the released SubscriptionDiscount.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found
86 404  Coupon not found
87 400  Coupon already used

Period balance

[Swagger:request:curl:getSubscriptionPeriodBalance]

The above command returns JSON structured like this

[Swagger:response:json:getSubscriptionPeriodBalance]

Calculate the balance of the subscription for the period containing the given date (defaults to now). The period balance describes how much have been paid (and the invoice paid with), how much of the paid amount that has been consumed and how much is remaining. Consumed and remaining amount is calculated from the fraction of the period that has already elapsed.

HTTP Request

GET https://api.reepay.com/v1/subscription/{handle}/period_balance

Query Parameters

[Swagger:request:table:getSubscriptionPeriodBalance]

Returns

Returns a SubscriptionPeriodBalance object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
12 404 Subscription not found

Add-on

Add-ons are templates for optional additional products that can be attached to a subscription. Add-ons attached to a subscription are called subscription add-ons. A subscription add-on will result in an additional charge billed each billing period in addition to a subscription’s base charge. An example on the use of add-ons can be found here.

The Add-On object

[Swagger:definition:json:AddOn]

[Swagger:definition:table:AddOn]

Get list of add-ons

[Swagger:request:curl:getAddOnList]

The above command returns JSON structured like this

[Swagger:response:json:getAddOnList]

Get list of add-ons. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/add_on

Query Parameters

[Swagger:request:table:getAddOnList]

Return

Returns a list response object containing Add-Ons in the content array.

Get add-on

[Swagger:request:curl:getAddOn]

The above command returns JSON structured like this

[Swagger:response:json:getAddOn]

Get add-on by handle.

HTTP Request

GET https://api.reepay.com/v1/add_on/{handle}

[Swagger:request:table:getAddOn]

Return

Returns an Add-on object.

Create add-on

[Swagger:request:curl:createAddOn]

The above command returns JSON structured like this

[Swagger:response:json:createAddOn]

An add-on is given a handle for own reference. Name will be reflected on the invoice.

HTTP Request

POST https://api.reepay.com/v1/add_on

[Swagger:request:table:createAddOn]

Return

Returns an Add-on object.

Update add-on

[Swagger:request:curl:updateAddOn]

The above command returns JSON structured like this

[Swagger:response:json:updateAddOn]

Update add-on

HTTP Request

PUT https://api.reepay.com/v1/add_on/{handle}

[Swagger:request:table:updateAddOn]

Return

Returns an Add-on object.

Delete add-on

[Swagger:request:curl:deleteAddOn]

The above command returns JSON structured like this

[Swagger:response:json:deleteAddOn]

Delete add-on.

HTTP Request

DELETE https://api.reepay.com/v1/add_on/{handle}

[Swagger:request:table:deleteAddOn]

Return

Returns the deleted Add-on object.

Undelete add-on

[Swagger:request:curl:undeleteAddOn]

The above command returns JSON structured like this

[Swagger:response:json:undeleteAddOn]

Undelete deleted add-on.

HTTP Request

POST https://api.reepay.com/v1/add_on/{handle}/undelete

[Swagger:request:table:undeleteAddOn]

Return

Returns the deleted Add-on object.

Additional cost

Additional costs can be added to subscriptions. Additional costs for a subscription will be collected at next renewal and added to the invoice. A maximum of 100 pending additional costs can be added to a subscription.

The Additional cost object

[Swagger:definition:json:AdditionalCost]

[Swagger:definition:table:AdditionalCost]

Create additional cost

[Swagger:request:curl:createAdditionalCostJson]

The above command returns JSON structured like this

[Swagger:response:json:createAdditionalCostJson]

An additional cost is given a handle for own reference. Order text will be reflected on the invoice. Notice that the amount is per quantity meaning that the total amount transferred to the invoice is quantity times amount.

HTTP Request

POST https://api.reepay.com/v1/additional_cost

[Swagger:request:table:createAdditionalCostJson]

Returns

Returns the new Additional cost object.

Get additional costs for subscription

[Swagger:request:curl:getAdditionalCosts]

The above command returns JSON structured like this

[Swagger:response:json:getAdditionalCosts]

Get all additional costs for subscription.

HTTP Request

GET https://api.reepay.com/v1/additional_cost/subscription/{handle}

[Swagger:request:table:getAdditionalCosts]

Returns

Returns an array of Additional costs objects.

Get additional cost

[Swagger:request:curl:getAdditionalCost]

The above command returns JSON structured like this

[Swagger:response:json:getAdditionalCost]

Get single additional cost by handle

HTTP Request

GET https://api.reepay.com/v1/additional_cost/{handle}

[Swagger:request:table:getAdditionalCost]

Returns

Returns an Additional costs objects.

Cancel pending additional cost

[Swagger:request:curl:cancelAdditionalCost]

The above command returns JSON structured like this

[Swagger:response:json:cancelAdditionalCost]

Cancel a pending additional cost

HTTP Request

POST https://api.reepay.com/v1/additional_cost/{handle}/cancel

[Swagger:request:table:cancelAdditionalCost]

Returns

Returns the cancelled pending Additional costs objects.

Credit

Credits can be added to subscriptions. Credits will be collected and deducted from invoice amount at next automatic renewal or optionally when a one-time invoice is created. If the credit amount is higher than the invoice amount, the remaining amount will be deducted from future invoices. Any additional costs will be added to the invoice amount before credit deduction.

Credits can also be created as a compensation when a subscription is put on-hold or changed. In this case the credit will reference an invoice credit note for the credited invoice.

A maximum of 100 pending credits can be added to a subscription.

The Credit object

[Swagger:definition:json:Credit]

[Swagger:definition:table:Credit]

Create credit

[Swagger:request:curl:createCreditJson]

The above command returns JSON structured like this

[Swagger:response:json:createCreditJson]

A credit is given a handle for own reference. Text will be reflected on the invoice.

HTTP Request

POST https://api.reepay.com/v1/credit

[Swagger:request:table:createCreditJson]

Return

Returns a Credit object.

Get credits for subscription

[Swagger:request:curl:getCredits]

The above command returns JSON structured like this

[Swagger:response:json:getCredits]

Get all credits for subscription.

HTTP Request

GET https://api.reepay.com/v1/credit/subscription/{handle}

[Swagger:request:table:getCredits]

Return

Returns an array of Credit objects.

Get credit

[Swagger:request:curl:getCredit]

The above command returns JSON structured like this

[Swagger:response:json:getCredit]

Get credit by handle

HTTP Request

GET https://api.reepay.com/v1/credit/{handle}

[Swagger:request:table:getCredit]

Return

Returns a Credit object.

Cancel credit

[Swagger:request:curl:cancelCredit]

The above command returns JSON structured like this

[Swagger:response:json:cancelCredit]

Cancel a pending credit

HTTP Request

POST https://api.reepay.com/v1/credit/{handle}/cancel

[Swagger:request:table:cancelCredit]

Return

Returns a Credit object.

Discount

Discounts are used as templates for discounts applied to subscriptions. A discount defines how much to discount, either fixed amount or percentage, what order lines to discount, and for how long to discount.

The Discount object

[Swagger:definition:json:Discount]

[Swagger:definition:table:Discount]

Get list of discounts

[Swagger:request:curl:getDiscountList]

The above command returns JSON structured like this

[Swagger:response:json:getDiscountList]

Get list of discounts. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/discount

Query Parameters

[Swagger:request:table:getDiscountList]

Return

Returns a list response object containing Discount in the content array.

Get discount

[Swagger:request:curl:getDiscount]

The above command returns JSON structured like this

[Swagger:response:json:getDiscount]

Get discount by handle.

HTTP Request

GET https://api.reepay.com/v1/discount/{handle}

[Swagger:request:table:getDiscount]

Return

Returns an Discount object.

Create discount

[Swagger:request:curl:createDiscount]

The above command returns JSON structured like this

[Swagger:response:json:createDiscount]

A discount is given a handle for own reference. Name will be reflected on the invoice.

HTTP Request

POST https://api.reepay.com/v1/discount

[Swagger:request:table:createDiscount]

Return

Returns an Discount object.

Update discount

[Swagger:request:curl:updateDiscount]

The above command returns JSON structured like this

[Swagger:response:json:updateDiscount]

HTTP Request

PUT https://api.reepay.com/v1/discount/{handle}

[Swagger:request:table:updateDiscount]

Return

Returns an Discount object.

Delete discount

[Swagger:request:curl:deleteDiscount]

The above command returns JSON structured like this

[Swagger:response:json:deleteDiscount]

Delete discount.

HTTP Request

DELETE https://api.reepay.com/v1/discount/{handle}

[Swagger:request:table:deleteDiscount]

Return

Returns the deleted Discount object.

Coupon

Coupons can be used to generate codes for discounts that can be redeemed for subscriptions, either at subscription creation or subsequently. Coupons are a great tool for a promotion, special offer, or sale strategy.

The Coupon object

[Swagger:definition:json:Coupon]

[Swagger:definition:table:Coupon]

Get list of coupons

[Swagger:request:curl:getCouponList]

The above command returns JSON structured like this

[Swagger:response:json:getCouponList]

Get list of coupons. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/coupon

Query Parameters

[Swagger:request:table:getCouponList]

Return

Returns a list response object containing Coupon in the content array.

Get coupon

[Swagger:request:curl:getCoupon]

The above command returns JSON structured like this

[Swagger:response:json:getCoupon]

Get coupon by handle.

HTTP Request

GET https://api.reepay.com/v1/coupon/{handle}

[Swagger:request:table:getCoupon]

Return

Returns a Coupon object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
86 404 Coupon not found

Create coupon

Create a coupon. The coupon code needs to be unique for the currently active coupons.

[Swagger:request:curl:createCoupon]

The above command returns JSON structured like this

[Swagger:response:json:createCoupon]

HTTP Request

POST https://api.reepay.com/v1/coupon

[Swagger:request:table:createCoupon]

Return

Returns a Coupon object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
11 400 Duplicate handle
88 400 Coupon code already exists
83 404 Discount not found
10 404 Plan provided in eligible plans not found

Update coupon

Some attributes can be updated on an active coupon.

[Swagger:request:curl:updateCoupon]

The above command returns JSON structured like this

[Swagger:response:json:updateCoupon]

HTTP Request

PUT https://api.reepay.com/v1/coupon/{handle}

[Swagger:request:table:updateCoupon]

Return

Returns a Coupon object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
86 404 Coupon not found
90 400 Coupon not active
91 400 Coupon cannot be updated because maximum redemptions is below the current number of redemptions

Expire coupon

An actie coupon can be expired early.

[Swagger:request:curl:expireCoupon]

The above command returns JSON structured like this

[Swagger:response:json:expireCoupon]

HTTP Request

POST https://api.reepay.com/v1/coupon/{handle}/expire

[Swagger:request:table:expireCoupon]

Return

Returns a Coupon object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
86 404 Coupon not found
90 400 Coupon not active

Delete coupon

An coupon with no redemptions can be deleted.

[Swagger:request:curl:deleteCoupon]

The above command returns JSON structured like this

[Swagger:response:json:deleteCoupon]

HTTP Request

DELETE https://api.reepay.com/v1/coupon/{handle}

[Swagger:request:table:deleteCoupon]

Return

Returns the deleted Coupon object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
86 404 Coupon not found
89 400 Coupon cannot be deleted because it has redemptions

Validate coupon code

Before actually redeeming a coupon code, it’s possible to test its validity and eligibility. The customer, plan, and subscription arguments are optional, but if they are not provided, the actual eligibility for the customer, plan, and subscription is not tested.

The customer argument must always be provided together with either the plan or the subscription argument, or both, in order to check the coupon’s validity against its redemption strategy.

For example, if a coupon’s redemption strategy is ‘once_per_plan,’ both the customer and plan must be provided to validate the coupon using the 'once per plan’ strategy. If the strategy is 'once_per_subscription,’ both the customer and subscription must be provided to validate the coupon using the 'once per subscription’ strategy. If the strategy is 'once_per_customer,’ only the customer needs to be provided to validate the coupon using the 'once per customer’ strategy. Otherwise, only the basic checks are performed.

The arguments needs to be provided as query parameters.

[Swagger:request:curl:validateCode]

The above command returns JSON structured like this

[Swagger:response:json:validateCode]

HTTP Request

GET https://api.reepay.com/v1/coupon/code/validate?code={code}&plan={plan}&customer={customer}&subscription={subscription}

[Swagger:request:table:validateCode]

Return

Returns eligible Coupon or failure. See below.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
86 404 Coupon code not found or coupon not eligible for use
87 400 Coupon already used by customer. Can only be returned if customer argument is given.
9 404 Customer for provided customer handle cannot be found

Invoice

Subscription billing, additional costs and credits are collected in invoices. An invoice is settled through card transactions or other types of transactions. Invoices are created automatically for new billing periods, but can also be created on demand for subscriptions and customers. See create invoice for subscription and create invoice for customer.

Subscription invoices are settled automatically and subject to an automated dunning process defined by the subscription plan. One-time on-demand invoices must be settled using a payment method from the customer wallet or with a manual transfer, e.g. bank transfer.

Invoices can also be settled or authorized using the Charge resource by providing existing payment method. Notice that this can only be done when the transaction is a merchant initiated transaction where the customer is not present.

A settled invoice can be refunded using the Refund resource.

The Invoice object

[Swagger:definition:json:Invoice]

[Swagger:definition:table:Invoice]

Get list of invoices

[Swagger:request:curl:getInvoiceList]

The above command returns JSON structured like this

[Swagger:response:json:getInvoiceList]

Get list of invoices. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/invoice

Query Parameters

[Swagger:request:table:getInvoiceList]

Parameter Type Description Example
range string Limiting time attribute: created or settled (default created) range=created
handle string Invoice handle prefix handle=order-1234
state stringlist Invoices with states state=dunning&state=pending
exclude_state stringlist Invoices without states exclude_state=created
customer string Invoices for customer customer=cust-1234
amount integerinterval Amount filtering amount=(0;20000]
refunded_amount integerinterval Refunded amount filtering refunded_amount=[30000;30000]
authorized_amount integerinterval Authorized amount filtering authorized_amount=[30000;30000]
currency stringlist Invoices with currency currency=USD&currency=GBP
partial_settled boolean Filter invoices based on partial settled.
If true invoices where authorized_amount < settled_amount is returned.
If false invoices where settled_amount = authorized_amount is returned.
partial_settled=true
type stringlist Invoices with types type=ch
subscription string Invoices for subscription subscription=sub-1234
plan string Invoices for subscription plan plan=plan-1234
dunning_start localdatetimeinterval Dunning start in interval dunning_start=[2022-01-01;2022-02-01]
dunning_success localdatetimeinterval Dunning success in interval dunning_success=[2022-01-01;2022-02-01]
number integer Invoice number if subscription invoice number=1002
due localdatetimeinterval Due in interval due=[2022-01-01;2022-01-02]

Return

Returns a list response object containing Invoices in the content array.

Examples

Get all invoices for a customer cust-007.

GET https://api.reepay.com/v1/list/invoice?customer=cust-007

Get all dunning invoices

GET https://api.reepay.com/v1/list/invoice?state=dunning

Get settled invoices for January 2022 with amount 20000 in DKK

GET https://api.reepay.com/v1/list/invoice?range=settled&amount=[20000;20000]&currency=DKK&from=2022-01-01&to=2022-02-01

Get invoices settled in March 2022 with refunded amount

GET https://api.reepay.com/v1/list/invoice?range=settled&refunded_amount=(0;)&from=2022-03-01&to=2022-04-01

Get invoice

[Swagger:request:curl:getInvoice]

The above command returns JSON structured like this

[Swagger:response:json:getInvoice]

Get invoice by id or handle

HTTP Request

GET https://api.reepay.com/v1/invoice/{id}

[Swagger:request:table:getInvoice]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found

Settle invoice

[Swagger:request:curl:settle]

The above command returns JSON structured like this

[Swagger:response:json:settle]

Settle pending, dunning or failed invoice using a customer payment method or subscription payment method for a subscription invoice. For a customer invoice an optional due date and time can be supplied delaying the settle until this date and time.

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/settle

[Swagger:request:table:settle]

Return

Returns an Invoice object. The invoice state depends on the origin of the invoice. A one-time customer invoice will be either settled or failed while a subscription invoice will keep its state if the settle fails.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
80  400 Invoice cannot be settled because it has processing transactions
76  400 Payment method not provided
40 404 Payment method not found
147 400 Stored payment method is in failed state and it is not allowed to retry because of scheme or payment provider rules

Cancel settle later

[Swagger:request:curl:cancelSettleLater]

The above command returns JSON structured like this

[Swagger:response:json:cancelSettleLater]

Scheduled settle later can be cancelled for at pending customer invoice

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/settle/cancel

[Swagger:request:table:cancelSettleLater]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
82 400 Invoice not in state pending

Offline manual settle

[Swagger:request:curl:manualSettle]

The above command returns JSON structured like this

[Swagger:response:json:manualSettle]

A non-settled invoice can be settled using an offline manual transfer. An offline manual transfer could for example be a cash or bank transfer not handled automatically by Reepay. The invoice will be instantly settled and a receipt email is sent to the customer.

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/manual_settle

[Swagger:request:table:manualSettle]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
79 400 Invoice already settled
105 400 Invoice is authorized
80 400 Invoice has processing transactions

Cancel invoice

[Swagger:request:curl:cancelInvoice]

The above command returns JSON structured like this

[Swagger:response:json:cancelInvoice]

An invoice with all transactions with no or only failed transaction can be cancelled. No further attempts to fulfill the invoice will be made. If the invoice is dunning the dunning process will be cancelled. If accounting_invoice_enabled is set to true at Invoice Configuration, then a credit note for cancelled invoice will be created.

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/cancel

[Swagger:request:table:cancelInvoice]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
29 400 Invoice already settled
30 400 Invoice has active transactions. All transactions must be failed, cancelled or pending

Force fail invoice

[Swagger:request:curl:failInvoice]

The above command returns JSON structured like this

[Swagger:response:json:failInvoice]

Force fail a pending or dunning invoice. If the invoice is dunning the dunning process will be cancelled. The state of potential subscription for the invoce is not affected. An invoice cannot be forced failed if it has processing transactions awaiting payment provider.

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/fail

[Swagger:request:table:failInvoice]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
82 400 Invoice wrong state - must be pending or dunning
30 400 Invoice has active transactions. All transactions must be failed, cancelled or pending

Invoice reactivate

[Swagger:request:curl:reactivateInvoice]

The above command returns JSON structured like this

[Swagger:response:json:reactivateInvoice]

A failed or cancelled invoice can be put back to state pending for processing. The invoice will potentially enter a new dunning process if it is a subscription invoice.

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/reactivate

[Swagger:request:table:reactivateInvoice]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
82  400 Invoice must be failed or cancelled
112 400 Invoice is a charge which cannot be re-activated

Detach from subscription

[Swagger:request:curl:detachFromSubscription]

The above command returns JSON structured like this

[Swagger:response:json:detachFromSubscription]

A subscription invoice with state pending, dunning or failed can be detached from the subscription and changed to a customer one-time invoice with pending state.

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/detach

[Swagger:request:table:detachFromSubscription]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
112 400 Invoice is not a subscription invoice
82 400 Invoice wrong state, it must be pending, dunning or failed
30 400 Invoice has active transactions, all must be failed, cancelled or pending

Cancel all dunning and pending

[Swagger:request:curl:cancelAllDunningPending]

The above command returns JSON structured like this

[Swagger:response:json:cancelAllDunningPending]

Cancel all dunning and pending invoices for a subscription.

HTTP Request

POST https://api.reepay.com/v1/invoice/cancel_all_dunning_pending/subscription/{handle}

[Swagger:request:table:cancelAllDunningPending]

Return

Returns an array of Invoice objects.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
30 400 Invoice has active transactions, all must be failed, cancelled or pending

Create or update billing address

[Swagger:request:curl:createOrUpdateBillingAddress]

Create or update invoice billing address

HTTP Request

PUT https://api.reepay.com/v1/invoice/{id}/billing_address

[Swagger:request:table:createOrUpdateBillingAddress]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found

Create or update shipping address

[Swagger:request:curl:createOrUpdateShippingAddress]

Create or update invoice shipping address

HTTP Request

PUT https://api.reepay.com/v1/invoice/{id}/shipping_address

[Swagger:request:table:createOrUpdateShippingAddress]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found

Delete billing address

[Swagger:request:curl:deleteBillingAddress]

Delete invoice billing address

HTTP Request

DELETE https://api.reepay.com/v1/invoice/{id}/billing_address

[Swagger:request:table:deleteBillingAddress]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found

Delete shipping address

[Swagger:request:curl:deleteShippingAddress]

Delete invoice shipping address

HTTP Request

DELETE https://api.reepay.com/v1/invoice/{id}/shipping_address

[Swagger:request:table:deleteShippingAddress]

Return

Returns an Invoice object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found

Credit note

A credit note is created on refunding or crediting invoice.

The Credit note object

[Swagger:definition:json:InvoiceCreditNote]

[Swagger:definition:table:InvoiceCreditNote]

Get Credit note

[Swagger:request:curl:getCreditNote]

The above command returns JSON structured like this

[Swagger:response:json:getCreditNote]

Get credit note by id or handle

HTTP Request

GET https://api.reepay.com/v1/credit_note/{id}

[Swagger:request:table:getCreditNote]

Return

Returns an Credit note object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found

Get list of credit notes

[Swagger:request:curl:getInvoiceCreditNoteList]

The above command returns JSON structured like this

[Swagger:response:json:getInvoiceCreditNoteList]

Get list of credit notes. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/credit_note

Query Parameters

[Swagger:request:table:getInvoiceCreditNoteList]

Return

Returns a list response object containing Credit notes in the content array.

Examples

Get all credit notes for a customer cust-007.

GET https://api.reepay.com/v1/list/credit_note?customer=cust-007

Get settled invoices for January 2022 with amount 20000 in DKK

GET https://api.reepay.com/v1/list/credit_note?amount=[20000;20000]&currency=DKK&from=2022-01-01&to=2022-02-01

Charge

Charges are an abstraction on top of invoices, providing a convenient way to charge customers with one-time payments and to pay existing unpaid invoices. Charges are basically a combination of an invoice and a payment transaction . Charges allow to pay either with a direct settle or with a two-step process consisting of an authorization reserving an amount, and a subsequent settle. The handle for a charge is also the invoice handle and can be seen as an order identification in own shopping system. If an invoice does not already exist an invoice will be created with state created and a payment transaction performed. After a payment attempt the resulting invoice will be in one of the following states: settled, authorized, failed, pending or pending. If the charge is failed it can be retried with the same handle. The pending state is only used for asynchronous payment methods (e.g. MobilePay Subscriptions) where the result of the charge operation is not known immediately. Webhooks must be used to listen for the state change. Card payments are always synchronous.

To create a charge a customer needs to be provided. This can either be a reference to an existing customer, or a create customer object. If a customer payment method (e.g. ca_..) is used a customer reference does not need to be provided as the payment method implicitly defines the customer. If an object is provided the customer will be created if the customer does not already exist in which case the existing customer will be used.

The amount for a charge is given either with the argument amount and optionally ordertext, or by providing a list of detailed order lines.

To create a charge a payment source must be provided with a reference to an existing payment method for the customer. E.g. ca_... for saved credit cards.

Notice that if Reepay Checkout is used as payment window, you do not need to create the charge directly. If will be created by Reepay Checkout.

The charge resource allows the use of an idempotency key to retry the same request multiple times. Multiple calls with the same key will yield the same result. This is convenient in cases of network outages where the result of a call is not received. In this case the same call can be retried. If the outcome a create charge is a failed charge a different idempotency key needs to be provided for a subsequent attempt to pay the same charge. Notice that even without using the idempotency key there is no risk of moving money twice when using the same handle. The operations around an invoice is locked, and an invoice can only be settled/authorized once.

The result of a charge can be monitored using webhooks by listening for the following events :

An authorized invoice must normally be settled within seven days before the authorization expire. An authorization can also be cancelled resulting in an attempt to void the reservation of money. A cancel will result in an invoice with state cancelled.

The Charge object

[Swagger:definition:json:Charge]

[Swagger:definition:table:Charge]

Get list of charges

[Swagger:request:curl:getChargeList]

The above command returns JSON structured like this

[Swagger:response:json:getChargeList]

Get list of charges. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/charge

Query Parameters

[Swagger:request:table:getChargeList]

Parameter Type Description Example
range string Limiting time attribute: created or settled (default created) range=created
handle string Invoice handle prefix handle=order-1234
state stringlist Invoices with states state=dunning&state=pending
exclude_state stringlist Invoices without states exclude_state=created
customer string Invoices for customer customer=cust-1234
amount integerinterval Amount filtering amount=(0;20000]
refunded_amount integerinterval Refunded amount filtering refunded_amount=[30000;30000]
authorized_amount integerinterval Authorized amount filtering authorized_amount=[30000;30000]
currency stringlist Invoices with currency currency=USD&currency=GBP
partial_settled boolean Filter invoices based on partial settled.
If true invoices where authorized_amount < settled_amount is returned.
If false invoices where settled_amount = authorized_amount is returned.
partial_settled=true

Return

Returns a list response object containing Charges in the content array.

Examples

Get settled charges for January 2022 with amount 20000 in DKK

GET https://api.reepay.com/v1/list/invoice?range=settled&amount=[20000;20000]&currency=DKK&from=2022-01-01&to=2022-02-01

Get charge

[Swagger:request:curl:getCharge]

The above command returns JSON structured like this

[Swagger:response:json:getCharge]

Get charge by invoice id or handle

HTTP Request

GET https://api.reepay.com/v1/charge/{handle}

[Swagger:request:table:getCharge]

Return

Returns a Charge object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found

Create charge

A charge is created by providing order details (if not existing invoice) and a payment source. The response is a HTTP 200 if the request is understood and processed by Reepay, but not necessarily with succesful charge. The HTTP status code relates to the communication with Reepay and Reepays ability to process the request, not the result of the charge. The result of the charge operation should be determined from the state parameter which will be settled, authorized, failed or pending. Errors relating to the payment method or acquirer processing, e.g. insufficient funds, or processing errors at the acquirer, will result in a HTTP 200 OK with a charge object with state failed and error indication in the error_state and error parameters. If the charge is failed it can be retried with the same handle. The pending state is only used for asynchronous payment methods (e.g. MobilePay Subscriptions) where the result of the charge operation is not known immediately. Webhooks must be used to listen for the state change. Card payments are always synchronous.

Even though the handle can be up to 255 characters it is not recommended to use more than 20 characters as this will allow for the use of handle as reference on bank statements without truncation.

Below is given recommended error handling for the charge operation.

Error Handling
Communication error (no HTTP respoonse)
or HTTP server error 5xx
Retry operation immediately or later, preferably with an idempotency key. Retry is important if instant settle is used as the settle operation can actually have gone through so money has been moved.
HTTP 400 client error and error code 147 The stored payment method referenced is in state failed, and it is not allowed to make charges because of scheme or payment provider rules. E.g. Visa Token Service token. Treat this the same way as a hard decline and mark payment method as failed and not eligible for use.
Other HTTP 4xx client errors Check your implementation. One error that can be expected is that invoice is already authorized or settled if no idempotency key is used and there has been a retry.
Other non 200 HTTP response Something is wrong. Handle as for communication error and contact Reepay if the problem persists.
state = authorized or state = settled Success
state = pending The charge has successfully been sent for asynchronous processing. The result of the charge will be given in webhook, or the state of the charge can be polled with get charge.
error_state = hard_declined The charge operation has been declined by acquirer or issuer. The hard decline means that no further attempts should be made using the same payment method. All subsequent attempts will fail. See below for potential scheme fees in case of excessive retrying.
error_state = soft_declined The charge operation has been declined by acquirer or issuer with a soft decline. This is ususally due to insufficient funds. Future attempts may succeed. See below for recommendation regarding retries and potential scheme fee in case of excessive retrying.
error_state = processing_error A processing error can happen if something goes wrong at, or in between, any of the parties involved in a transaction. A processing error can potentially have resulted in a successful charge, but the result never reaches Reepay. E.g. a timeout somewhere in the chain. Processing errors leading to transactions actually having been completed without knowing the result is frustrating, but luckily quite rare. We recommend to retry later on a processing error but if the error persists for days the payment method should be marked as failed.

Retries

Schemes have implemented fees on excessive retries to enforce their rules prohibiting excessive payment reattempts. Visa’s rules broadly prohibit more than 15 retries of a single payment over 30 calendar days. Mastercard disallows more than 10 reattempts within a 24-hour period. We recommend not to retry hard declined cards and limit retrying on soft declines to once every 24 hours and at most 15 times.

[Swagger:request:curl:createCharge]

The above command returns JSON structured like this

[Swagger:response:json:createCharge]

HTTP Request

POST https://api.reepay.com/v1/charge

[Swagger:request:table:createCharge]

Return

Returns a Charge object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
79 400 Invoice already settled
105 400 Invoice already authorized
29  400 Invoice already cancelled
71 400 The customer is deleted
11 400 Duplicate customer handle provided
18  400 Customer could not be determined from either reference, create customer object or payment method source
99  400 Customer object given does not match handle of existing customer or handle given does not match existing customer reference
40 404 Payment method not found
34 400 Invalid card token
24 400 No amount or order lines was provided
80 400 Existing charge has processing transactions
100 400 Amount change is not allowed when charging an existing invoice
72 400 Currency change not allowed on existing invoice or charge
147 400 Stored payment method is in failed state and it is not allowed to retry because of scheme or payment provider rules

Prepare charge

A charge can be prepared in Reepay without a payment attempt. The charge can subsequently be attempted paid with a call to create charge. A prepare charge operation is basically a create charge operation without payment source. A prepared charge operation will result in an invoice with state created. The prepare charge operation can be used to create an order before determining how to pay for the invoice.

[Swagger:request:curl:prepareCharge]

The above command returns JSON structured like this

[Swagger:response:json:prepareCharge]

HTTP Request

POST https://api.reepay.com/v1/charge/prepare

[Swagger:request:table:prepareCharge]

Return

Returns a Charge object.

Errors

The operation can generate the same erros as a create charge operation.

Settle charge

[Swagger:request:curl:settleCharge]

The above command returns JSON structured like this

[Swagger:response:json:settleCharge]

Settle an authorized charge. This is the second step in a two-step payment process with an authorization and subsequent settle. Optionally the amount and order lines of the charge can be adjusted. Multiple settles can be performed up to the authorized amount if the payment method allows this. If order lines are provided the first settle will change the order lines and subsequent settles will add the order lines provided.

Errors relating to acquirer declines and acquirer processing errors will result in a HTTP 200 OK with an error description in the error_state and error parameters. For processing errors the state is left unchanged. For irrecoverable acquirer declines for the first settle, the state of the charge will be changed to failed. Use the error_state, error and state parameters to determine if the operation was successful. If only one settle is performed the state parameter can solely be used. It should be settled after successful settle. For multiple settles the state is already settled so the error and/or error_state parameter must be used to determine success.

Error handling if a settle operation fails is important, as this is a money carrying operation. We recommend using an idempotency key for retrying the same settle operation. This is especially important for partial settles so a retry does not result in additional partial captures. Our recommendations for error handling is given in the tables below.

Error Handling
Communication error (no HTTP respoonse)
or HTTP server error 5xx
Retry operation immediately or later, preferably with an idempotency key to avoid multiple settles if a partial settle is performed. Retry is important as the settle operation can actually have gone through so money has been moved.
HTTP client error 4xx Check your implementation. One error that can be expected for full settles, and if an idempotency key is not used is “Invoice already settled”, as described below. For a retry it can be interpreted as success if the idempotency key is not used.
Other non 200 HTTP response Something is wrong. Handle as for communication error and contact Reepay if the problem persists.
state = settled and error_state = <null> Success
error_state = hard_declined The settle operation has been declined by acquirer or issuer. No further attempts should be made.
error_state = soft_declined In rare occasions the result of a settle operation can be a soft decline (possibly recoverable). A retry could be performed later, but is not required, as no money has been moved. Most notable soft decline is for acquirer Nets and Forbrugsforeningen cards. Partial captures need to be 24 hours apart, otherwise the following acquirer_code is returned in addition to the soft decline 999. In this case wait until 24 hours has elapsed since last settle.

When retrying a new idempotency key must be used as it is a separate transaction.
error_state = processing_error A processing error can happen if something goes wrong at, or in between, any of the parties involved in a transaction. A processing error can potentially have resulted in an approved settle, but the result never reaches Reepay. E.g. a timeout somewhere in the chain. Processing errors leading to transactions actually having been completed without knowing the result is frustrating, but luckily quite rare.

We recommend to retry later on a processing error, but only a few times.

HTTP Request

POST https://api.reepay.com/v1/charge/{handle}/settle

[Swagger:request:table:settleCharge]

Return

Returns a Charge object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
79 400 Invoice already settled - no remaining authorized amount to settle
106 400 Invoice not authorized
102 400 New amount provided is higher than the authorized amount
129 400 Multiple settles not allowed - invoice has already been settled once and payment method does not allow multiple settles
130 400 Partial settle not allowed - payment method does not allow a partial settle

Cancel charge

[Swagger:request:curl:cancelCharge]

The above command returns JSON structured like this

[Swagger:response:json:cancelCharge]

Cancel an authorized charge. A void of reserved money will be attempted.

HTTP Request

POST https://api.reepay.com/v1/charge/{handle}/cancel

[Swagger:request:table:cancelCharge]

Return

Returns a Charge object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
106 400 Invoice not authorized
108 500 Charge cancel failed because of acqurier error or rejection. See transaction_error See transaction errors.

Delete created charge

[Swagger:request:curl:deleteCreatedInvoice]

The above command returns JSON structured like this

[Swagger:response:json:deleteCreatedInvoice]

Delete a charge in state created.

HTTP Request

DELETE https://api.reepay.com/v1/charge/{handle}

[Swagger:request:table:deleteCreatedInvoice]

Return

Returns HTTP response code 204 and no content on success.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
82 400 Invoice wrong state, must be created

Transaction

Transactions are the money carrying entities paying and refunding invoices. An invoice can have multiple transactions. E.g. an authorization transaction, multiple settle transactions and multiple refund transactions. Some might be successful, others can be failed.

The transaction object

[Swagger:definition:json:Transaction]

[Swagger:definition:table:Transaction]

Get list of transactions

[Swagger:request:curl:getTransactionList]

The above command returns JSON structured like this

[Swagger:response:json:getTransactionList]

Get list of transaction. See List queries for a general introduction to list operations. Note that excessive usage will be considered unfair API usage.

HTTP Request

GET https://api.reepay.com/v1/list/transaction

Query Parameters

[Swagger:request:table:getTransactionList]

Return

Returns a list response object containing Transactions in the content array.

Examples

Get all transactions for an invoice inv-007.

GET https://api.reepay.com/v1/list/transaction?invoice=inv-007

Get Apple Pay transactions

GET https://api.reepay.com/v1/list/transaction?payment_type=applepay

Get settled transactions for January 2022 with amount 20000 in DKK

GET https://api.reepay.com/v1/list/transaction?range=settled&amount=[20000;20000]&currency=DKK&from=2022-01-01&to=2022-02-01

Get refunded transactions in March 2022

GET https://api.reepay.com/v1/list/invoice?range=refunded&from=2022-03-01&to=2022-04-01

Get transaction

[Swagger:request:curl:transaction]

The above command returns JSON structured like this

[Swagger:response:json:transaction]

HTTP Request

GET https://api.reepay.com/v1/invoice/{id}/transaction/{transaction}

[Swagger:request:table:transaction]

Return

Returns a Transaction object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
70  404 Transaction not found

Cancel transaction

[Swagger:request:curl:cancelTransaction]

The above command returns JSON structured like this

[Swagger:response:json:cancelTransaction]

Cancel a pending, authorized or processing transaction. Not all processing transactions can be cancelled, it depends on the payment method.

HTTP Request

POST https://api.reepay.com/v1/invoice/{id}/transaction/{transaction}/cancel

[Swagger:request:table:cancelTransaction]

Return

Returns a Transaction object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
70  404 Transaction not found
109 400 Transaction wrong state must be pending, authorized or processing (in some cases)
108 500 Transaction cancel failed in case of authorization because of acqurier rejection or error. See transaction_error See transaction errors.

Get transaction details

Get the payment provider specific details for a transaction. This is an unstructured response that is different for each payment provider.

[Swagger:request:curl:transactionDetails]

The above command returns JSON structured like this

[Swagger:response:json:transactionDetails]

HTTP Request

GET https://api.reepay.com/v1/invoice/{id}/transaction/{transaction}/details

[Swagger:request:table:transactionDetails]

Return

Returns a JSON object with acquirer specific key/value details for the transaction.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
70  404 Transaction not found

Refund

The refund resource allows refunds on settled invoices/charges. Multiple refunds (depending on payment method) can be created for an invoice but only up to the settled amount can be refunded. A successful refund will result in a credit note attached to the invoice. Amount is optional and can be specified either as a single amount or as a list of credit note lines which optionally can be linked to the order lines on the invoice.

The refund resource allows the use of an idempotency key to safely retry the same request multiple times. Multiple calls with the same key will yield the same result with no risk of money being moved twice. This is convenient in cases of network outages where the result of a call is not received. In this case the same call can be retried.

The result of a refund can be monitored using webhooks by listening for the following event: invoice_refund. The webhook will contain a transaction reference which is the same as the refund id. The details of the refund can be retrieved by getting the refund using this id.

A refund is normally performed as an online refund using the settled transaction, e.g. a credit card transaction where money is transferred back to the card. A refund can optionally instead be an offline manual refund. An offline manual refund could for example be a bank transfer or chargeback handled outside Reepay and not automatically by Reepay. For an invoice settled with a manual transfer, a refund must be an offline manual refund.

For some payment methods other than credit card, the refund operation can be asynchronous meaning that the result of the operation is not known right away. In this case the returned state for the refund will be processing. The result of the operation will be given by webhooks. The event will either be invoice_refund or invoice_refund_failed. Notice that the event invoice_refund_failed is only sent in the asynchronous case.

The Refund object

[Swagger:definition:json:Refund]

[Swagger:definition:table:Refund]

Get refund

[Swagger:request:curl:getRefund]

The above command returns JSON structured like this

[Swagger:response:json:getRefund]

Get refund by id

HTTP Request

GET https://api.reepay.com/v1/refund/{id}

[Swagger:request:table:getRefund]

Return

Returns a Refund object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
107 404 Refund not found

Create refund

The response is a HTTP 200 if the request is understood and processed by Reepay, but not necessarily with success. The HTTP status code relates to the communication with Reepay and Reepays ability to process the request, not the result of the refund. The result of the refund operation should be determined from the state parameter which will be refunded, failed or processing (only asynchronous payment methods). The error state and error reason can be found in error_state and error parameters.

Error handling if a refund operation fails is important, as this is a money carrying operation. We recommend using an idempotency key for retrying the same refund operation. This is especially important for partial refunds so a retry does not result in additional partial refund. Our recommendations for error handling is given in the tables below.

Error Handling
Communication error (no HTTP respoonse)
or HTTP server error 5xx
Retry operation immediately or later, preferably with an idempotency key to avoid multiple refunds if a partial refund is performed. Retry is important as the refund operation can actually have gone through so money has been moved.
HTTP client error 4xx Check your implementation. One error that can be expected for full refunds, and if an idempotency key is not used is “Refund amount too high”, as described below. For a retry it can be interpreted as success if the idempotency key is not used.
Other non 200 HTTP response Something is wrong. Handle as for communication error and contact Reepay if the problem persists.
state = refunded Success
state = processing Success - The payment type has asynchronous refunds (e.g. MobilePay Subscriptions). The result of the refund will be deliverd in webhook.
error_state = hard_declined The refund operation has been declined by acquirer or issuer. No further attempts with same arguments will succeed.
error_state = processing_error A processing error can happen if something goes wrong at, or in between, any of the parties involved in a transaction. A processing error can potentially have resulted in an approved refund, but the result never reaches Reepay. E.g. a timeout somewhere in the chain. Processing errors leading to transactions actually having been completed without knowing the result is frustrating, but luckily quite rare.

We recommend to retry later on a processing error, but only a few times.

[Swagger:request:curl:createRefund]

The above command returns JSON structured like this

[Swagger:response:json:createRefund]

HTTP Request

POST https://api.reepay.com/v1/refund

[Swagger:request:table:createRefund]

Return

Returns a Refund object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
31 404 Invoice not found
64 400 Invoice not settled
65 400 The refund amount exceeds settled amount minus already refunded or credited amounts
80 400 Invoice has processing transactions - an asynchronous refund is in progress - result will be reported in webhook

Payout

The payout resource allows to create payouts to saved credit cards. That is credits without a previously settled charge. This functionality requires a card acquiring agreement able to perform payouts.

The Payout object

[Swagger:definition:json:Payout]

[Swagger:definition:table:Payout]

Get payout

[Swagger:request:curl:getPayout]

The above command returns JSON structured like this

[Swagger:response:json:getPayout]

Get payout by handle

HTTP Request

GET https://api.reepay.com/v1/payout/{id}

[Swagger:request:table:getPayout]

Return

Returns a Payout object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
137 404 Payout not found

Create payout

The response is a HTTP 200 if the request is understood and processed by Reepay, but not necessarily with success. The HTTP status code relates to the communication with Reepay and Reepays ability to process the request, not the result of the payout. The result of the payout operation should be determined from the state parameter which will be paid, failed or processing (only asynchronous payment methods). The error state and error reason can be found in error_state and error parameters of the latest payout transaction.

Error handling if a payout operation fails is important, as this is a money carrying operation.

Error Handling
Communication error (no HTTP respoonse)
or HTTP server error 5xx
Retry operation immediately or later. Retry is important as the refund operation can actually have gone through so money has been moved.
HTTP client error 4xx Check your implementation.
Other non 200 HTTP response Something is wrong. Handle as for communication error and contact Reepay if the problem persists.
state = paid Success
state = processing Success - The payment type has asynchronous payouts. The result of the refund will be deliverd in webhook.
error_state = hard_declined The refund operation has been declined by acquirer or issuer. No further attempts with same arguments will succeed.
error_state = processing_error A processing error can happen if something goes wrong at, or in between, any of the parties involved in a transaction. A processing error can potentially have resulted in an approved payout, but the result never reaches Reepay. E.g. a timeout somewhere in the chain. Processing errors leading to transactions actually having been completed without knowing the result is frustrating, but luckily quite rare.

We recommend to retry later on a processing error, but only a few times.

[Swagger:request:curl:createPayout]

The above command returns JSON structured like this

[Swagger:response:json:createPayout]

HTTP Request

POST https://api.reepay.com/v1/payout

[Swagger:request:table:createPayout]

Return

Returns a Payout object.

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
40 404 Payment method not found
135 400 Payment method not allowed for payout
136 400 Customer cannot be changed for payout attempt on previously failed payout

Event

Certain events are recorded in the Reepay system and are the triggers for sending mails and issuing webhooks. An event is tied to one or more of the main resources: customer, subscription and invoice. An event can be tied to several resources, e.g. an event tied to invoice will also be tied to customer and for subscription invoices also to a subscription.

Invoice events

Event Description
invoice_created Invoice has been created
invoice_settled Invoice has been settled
invoice_authorized Invoice has been authorized
invoice_dunning Invoice has entered dunning state
invoice_dunning_notification Time for sending dunning notification acording to dunning plan
invoice_dunning_cancelled An ongoing dunning process has been cancelled either because the invoice has been settled or because the invoice has been cancelled
invoice_failed Invoice has failed. A failed may later be authorized, settled, cancelled or fail again. For subscription invoices due to an unsuccessful dunning process or because of instant ondemand settle fail.
invoice_refund A refund has been performed on a settled invoice
invoice_refund_failed For asynchronous refund this event will be fired if the refund fails. An asynchronous refund will be indicated by the refund state processing when performing the refund.
invoice_reactivate A failed or cancelled invoice has been reactivated to state pending for processing
invoice_cancelled Invoice has been cancelled
invoice_changed State has not changed but other attributes on the invoice has changed. E.g. settle later cancel.
invoice_credited Invoice has been credited by creating attached an credit note and creating a subscription credit

Subscription events

Event Description
subscription_created Subscription has been created
subscription_payment_method_added A payment method has been added to the subscription for the first time
subscription_payment_method_changed The payment method has been changed for a subscription with an existing payment method
subscription_trial_end The trial period for subscription has ended
subscription_renewal An invoice has been made and new billing period has started for subscription
subscription_cancelled Subscription has been cancelled to expire at end of current billing period
subscription_uncancelled A previous cancellation has been cancelled
subscription_on_hold Subscription has been put on hold by request
subscription_on_hold_dunning Subscription has been put on hold due to a failed dunning process
subscription_reactivated Subscription on hold has been reactivated to active state
subscription_expired Subscription has expired either by request, end of fixed life time or because cancelled and billing period has ended
subscription_expired_dunning Subscription has expired due to a failed dunning process
subscription_changed Subscription scheduling or pricing has been changed, e.g. by changed plan or changed next period start

Customer events

Event Description
customer_created Customer has been created
customer_changed Customer information has been changed
customer_deleted Customer has been deleted
customer_payment_method_added A payment method has been added to customer
customer_payment_method_failed Payment method has entered failed state and should not be used again for future payments
customer_payment_method_updated Payment method has been updated, e.g. for EMV tokens when the underlying card changes resulting in new masked card number and changed expiry date.
customer_payment_method_reactivated Failed payment method is put back to state active. Can happen for EMV tokens if a suspended token is resumed. Can happen for credit cards if a faild card is retried with success.
customer_payment_method_deleted A payment method has been deleted in the Admin or with API call

The Event object

[Swagger:definition:json:Event]

[Swagger:definition:table:Event]

Get list of events

[Swagger:request:curl:getEvents]

The above command returns JSON structured like this

[Swagger:response:json:getEvents]

Events for account can be fetched in slices with no indication on total number of events. The list can be filtered on customer, subscription and invoice. Events will be ordered descending by creation date.

HTTP Request

GET https://api.reepay.com/v1/event?page={page}&size={size}&customer={customer}&subscription={subscription}&invoice={invoice}

Query Parameters

[Swagger:request:table:getEvents]

Return

An array of Event objects.

Get event

[Swagger:request:curl:getEvent]

The above command returns JSON structured like this

[Swagger:response:json:getEvent]

Get single event by id

HTTP Request

GET https://api.reepay.com/v1/event/{id}

[Swagger:request:table:getEvent]

Return

A Event object.

Metadata

Reepay offers metadata to store additional/custom data at the resource level. Metadata can be used to store things like:

Metadata can be defined for the following resources:

Metadata can be manipulated as a subresource, but it can also be created as part of the resource create operation. All create operations for the resources above have an optional metadata field to allow creation of resource and metadata in one atomic operation.

The metadata must be in valid JSON format and have a maximum size of 4KB.

Get metadata

curl -X GET \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Content-Type: application/json' \
https://api.reepay.com/v1/add_on/{handle}/metadata

The above command returns JSON structured like this

{
    "key1": "val1",
    "key2": "val2"
}

Get metadata for resource

HTTP Requests

GET https://api.reepay.com/v1/customer/{handle}/metadata

GET https://api.reepay.com/v1/subscription/{handle}/metadata

GET https://api.reepay.com/v1/plan/{handle}/metadata

GET https://api.reepay.com/v1/add_on/{handle}/metadata

GET https://api.reepay.com/v1/invoice/{handle}/metadata

[Swagger:request:table:getMetadata]

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
8 404 Not found (no metadata for resource)

I addition can the resource return resource specific 404 not found errors. See GET operations for resources to see the specific error code. E.g. code 9 for customer not found.

Create/update metadata

curl -X PUT \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "key1": "val1",
  "key2": "val2"
}' \
https://api.reepay.com/v1/customer/{handle}/metadata

The above command returns JSON structured like this

{
    "key1": "val1",
    "key2": "val2"
}

Create/update metadata for resource

HTTP Requests

PUT https://api.reepay.com/v1/customer/{handle}/metadata

PUT https://api.reepay.com/v1/subscription/{handle}/metadata

PUT https://api.reepay.com/v1/plan/{handle}/metadata

PUT https://api.reepay.com/v1/add_on/{handle}/metadata

PUT https://api.reepay.com/v1/invoice/{handle}/metadata

[Swagger:request:table:getMetadata]

Errors

The operation can generate the generic HTTP error codes described here and return resource specific not found errors. See GET operations for resources to see specific not found error codes.

Delete metadata

curl -X DELETE \
-u 'priv_12051dfac75143fc827cf63a87f46df3:' \
https://api.reepay.com/v1/customer/{handle}/metadata

Delete metadata for resource

HTTP Requests

DELETE https://api.reepay.com/v1/customer/{handle}/metadata

DELETE https://api.reepay.com/v1/subscription/{handle}/metadata

DELETE https://api.reepay.com/v1/plan/{handle}/metadata

DELETE https://api.reepay.com/v1/add_on/{handle}/metadata

DELETE https://api.reepay.com/v1/invoice/{handle}/metadata

[Swagger:request:table:getMetadata]

Errors

The operation can generate the following errors beside the generic HTTP error codes described here.

Errror code  HTTP code Description
8 404 Not found (no metadata for resource)

I addition can the resource return resource specific 404 not found errors. See GET operations for resources to see the specific error code. E.g. code 9 for customer not found.

Webhook

Webhooks issued by Reepay can be queried through the API and can be re-issued by request. A webhook is tied to a certain event but several webhooks can exist for a single event if multiple URL’s are used to receive webhooks. See also Event and Webhook in the introduction.

The Webhook object

[Swagger:definition:json:Webhook]

[Swagger:definition:table:Webhook]

Get list of webhooks

[Swagger:request:curl:getWebhooks]

The above command returns JSON structured like this

[Swagger:response:json:getWebhooks]

Get list of webhooks in pages. The lists are sorted descending by created date. Use the last created date from current page as the created_before parameter to request the next page.

HTTP Request

GET https://api.reepay.com/v1/webhook?size={size}&state={state}&created_before={created_before}

Query Parameters

[Swagger:request:table:getWebhooks]

Returns

Returns an array of Webhooks.

Get webhooks

[Swagger:request:curl:getWebhook]

The above command returns JSON structured like this

[Swagger:response:json:getWebhook]

Get webhook by id or by event id. An event can spawn multiple webhooks.

HTTP Request

GET https://api.reepay.com/v1/webhook/{id}

[Swagger:request:table:getWebhook]

Returns

Returns an array of Webhooks

Get webhook requests

[Swagger:request:curl:getWebhookRequests]

The above command returns JSON structured like this

[Swagger:response:json:getWebhookRequests]

Get list of webhook requests for a webhook. The list is sorted descending by time.

HTTP Request

GET https://api.reepay.com/v1/webhook/{id}/request

[Swagger:request:table:getWebhookRequests]

Returns

Returns an array of WebhookRequests

Re-send webhooks

[Swagger:request:curl:resendJson]

The above command returns JSON structured like this

[Swagger:response:json:resendJson]

Webhooks can be re-sent. A list of webhook ids or event ids identifying the webhooks must be provided. A maximum of 100 ids is allowed for each request.

HTTP Request

POST https://api.reepay.com/v1/webhook/resend

[Swagger:request:table:resendJson]

Returns

Returns an array of Webhooks, containing all the webhooks which has been scheduled for re-send. The webhooks state will have been changed back to pending.

Disable webhooks

[Swagger:request:curl:disableWebhooks]

The above command returns JSON structured like this

[Swagger:response:json:disableWebhooks]

Pending webhooks can be disabled. A list of webhook ids or event ids identifying the webhooks must be provided. A maximum of 100 ids is allowed for each request.

HTTP Request

POST https://api.reepay.com/v1/webhook/disable

[Swagger:request:table:disableWebhooks]

Returns

Returns an array of Webhooks, containing all the webhooks which has been disabled. The webhooks state will have been changed to disabled.

Update webhooks

[Swagger:request:curl:updateWebhooks]

The above command returns JSON structured like this

[Swagger:response:json:updateWebhooks]

Webhooks can be updated and re-sent in one operation. New URL, optional HTTP username, optional HTTP password, and a list of webhook ids or event ids identifying the webhooks must be provided. A maximum of 100 ids is allowed for each request.

HTTP Request

POST https://api.reepay.com/v1/webhook/update

[Swagger:request:table:updateWebhooks]

Returns

Returns an array of Webhooks, containing all the updated webhooks. The webhooks state will have been set to pending.

Object definitions

Account

[Swagger:definition:json:Account]

[Swagger:definition:table:Account]

Invoice

[Swagger:definition:json:Invoice]

[Swagger:definition:table:Invoice]

Transaction

[Swagger:definition:json:Transaction]

[Swagger:definition:table:Transaction]

ChargeSource

[Swagger:definition:json:ChargeSource]

[Swagger:definition:table:ChargeSource]

AdditionalCost

[Swagger:definition:json:AdditionalCost]

[Swagger:definition:table:AdditionalCost]

Customer

[Swagger:definition:json:Customer]

[Swagger:definition:table:Customer]

UpdateDunningPlan

[Swagger:definition:json:UpdateDunningPlan]

[Swagger:definition:table:UpdateDunningPlan]

CreateCustomerNote

[Swagger:definition:json:CreateCustomerNote]

[Swagger:definition:table:CreateCustomerNote]

CreditInvoice

[Swagger:definition:json:CreditInvoice]

[Swagger:definition:table:CreditInvoice]

ChangeNextPeriodStart

[Swagger:definition:json:ChangeNextPeriodStart]

[Swagger:definition:table:ChangeNextPeriodStart]

IntervalAmount

[Swagger:definition:json:IntervalAmount]

[Swagger:definition:table:IntervalAmount]

CreateSubscriptionPlan

[Swagger:definition:json:CreateSubscriptionPlan]

[Swagger:definition:table:CreateSubscriptionPlan]

CreateSubscription

[Swagger:definition:json:CreateSubscription]

[Swagger:definition:table:CreateSubscription]

SubscriptionChange

[Swagger:definition:json:SubscriptionChange]

[Swagger:definition:table:SubscriptionChange]

PreparedSubscription

[Swagger:definition:json:PreparedSubscription]

[Swagger:definition:table:PreparedSubscription]

ChangedSubscription

[Swagger:definition:json:ChangedSubscription]

[Swagger:definition:table:ChangedSubscription]

SubscriptionChangeJournal

[Swagger:definition:json:SubscriptionChangeJournal]

[Swagger:definition:table:SubscriptionChangeJournal]

CreateCreditNoteLine

[Swagger:definition:json:CreateCreditNoteLine]

[Swagger:definition:table:CreateCreditNoteLine]

PaymentMethods

[Swagger:definition:json:PaymentMethods]

[Swagger:definition:table:PaymentMethods]

CardVerification

[Swagger:definition:json:CardVerification]

[Swagger:definition:table:CardVerification]

SetCardPaymentMethod

[Swagger:definition:json:SetCardPaymentMethod]

[Swagger:definition:table:SetCardPaymentMethod]

UpdateUserPassword

[Swagger:definition:json:UpdateUserPassword]

[Swagger:definition:table:UpdateUserPassword]

CardToken

[Swagger:definition:json:CardToken]

[Swagger:definition:table:CardToken]

Subscription

[Swagger:definition:json:Subscription]

[Swagger:definition:table:Subscription]

WebhookRequest

[Swagger:definition:json:WebhookRequest]

[Swagger:definition:table:WebhookRequest]

UpdateCustomer

[Swagger:definition:json:UpdateCustomer]

[Swagger:definition:table:UpdateCustomer]

ChangePlan

[Swagger:definition:json:ChangePlan]

[Swagger:definition:table:ChangePlan]

[Swagger:definition:json:SubscriptionLinks]

[Swagger:definition:table:SubscriptionLinks]

CreateSubscriptionInvoice

[Swagger:definition:json:CreateSubscriptionInvoice]

[Swagger:definition:table:CreateSubscriptionInvoice]

CreateCustomerInvoice

[Swagger:definition:json:CreateCustomerInvoice]

[Swagger:definition:table:CreateCustomerInvoice]

Card

[Swagger:definition:json:Card]

[Swagger:definition:table:Card]

CardV2

[Swagger:definition:json:CardV2]

[Swagger:definition:table:CardV2]

MpsSubscriptionV2

[Swagger:definition:json:MpsSubscriptionV2]

[Swagger:definition:table:MpsSubscriptionV2]

MpsSubscription

[Swagger:definition:json:MpsSubscription]

[Swagger:definition:table:MpsSubscription]

CardTransaction

[Swagger:definition:json:CardTransaction]

[Swagger:definition:table:CardTransaction]

MpsTransaction

[Swagger:definition:json:MpsTransaction]

[Swagger:definition:table:MpsTransaction]

ManualTransaction

[Swagger:definition:json:ManualTransaction]

[Swagger:definition:table:ManualTransaction]

DunningPlan

[Swagger:definition:json:DunningPlan]

[Swagger:definition:table:DunningPlan]

CreditNoteLine

[Swagger:definition:json:CreditNoteLine]

[Swagger:definition:table:CreditNoteLine]

InvoiceCreditNote

[Swagger:definition:json:InvoiceCreditNote]

[Swagger:definition:table:InvoiceCreditNote]

Key

[Swagger:definition:json:Key]

[Swagger:definition:table:Key]

Credit

[Swagger:definition:json:Credit]

[Swagger:definition:table:Credit]

WebhookSettings

[Swagger:definition:json:WebhookSettings]

[Swagger:definition:table:WebhookSettings]

CreateOrderLine

[Swagger:definition:json:CreateOrderLine]

[Swagger:definition:table:CreateOrderLine]

UpdateAccount

[Swagger:definition:json:UpdateAccount]

[Swagger:definition:table:UpdateAccount]

UpdateOrganisation

[Swagger:definition:json:UpdateOrganisation]

[Swagger:definition:table:UpdateOrganisation]

CreateAdditionalCost

[Swagger:definition:json:CreateAdditionalCost]

[Swagger:definition:table:CreateAdditionalCost]

CreateSubscriptionAdditionalCost

[Swagger:definition:json:CreateSubscriptionAdditionalCost]

[Swagger:definition:table:CreateSubscriptionAdditionalCost]

UpdateSubscriptionPlan

[Swagger:definition:json:UpdateSubscriptionPlan]

[Swagger:definition:table:UpdateSubscriptionPlan]

OrderLine

[Swagger:definition:json:OrderLine]

[Swagger:definition:table:OrderLine]

CustomerSearch

[Swagger:definition:json:CustomerSearch]

[Swagger:definition:table:CustomerSearch]

CardImport

[Swagger:definition:json:CardImport]

[Swagger:definition:table:CardImport]

SupersedeSubscriptionPlan

[Swagger:definition:json:SupersedeSubscriptionPlan]

[Swagger:definition:table:SupersedeSubscriptionPlan]

CreateDunningPlan

[Swagger:definition:json:CreateDunningPlan]

[Swagger:definition:table:CreateDunningPlan]

InvoiceSearch

[Swagger:definition:json:InvoiceSearch]

[Swagger:definition:table:InvoiceSearch]

UpdateWebhookSettings

[Swagger:definition:json:UpdateWebhookSettings]

[Swagger:definition:table:UpdateWebhookSettings]

RefundInvoice

[Swagger:definition:json:RefundInvoice]

[Swagger:definition:table:RefundInvoice]

SubscriptionSearch

[Swagger:definition:json:SubscriptionSearch]

[Swagger:definition:table:SubscriptionSearch]

CustomerNote

[Swagger:definition:json:CustomerNote]

[Swagger:definition:table:CustomerNote]

Organisation

[Swagger:definition:json:Organisation]

[Swagger:definition:table:Organisation]

WebhookResendRequest

[Swagger:definition:json:WebhookResendRequest]

[Swagger:definition:table:WebhookResendRequest]

Plan

[Swagger:definition:json:Plan]

[Swagger:definition:table:Plan]

CreateCredit

[Swagger:definition:json:CreateCredit]

[Swagger:definition:table:CreateCredit]

EventList

[Swagger:definition:json:EventList]

[Swagger:definition:table:EventList]

Event

[Swagger:definition:json:Event]

[Swagger:definition:table:Event]

Webhook

[Swagger:definition:json:Webhook]

[Swagger:definition:table:Webhook]

CreateCustomer

[Swagger:definition:json:CreateCustomer]

[Swagger:definition:table:CreateCustomer]

Settle

[Swagger:definition:json:Settle]

[Swagger:definition:table:Settle]

ManualSettleTransfer

[Swagger:definition:json:ManualSettleTransfer]

[Swagger:definition:table:ManualSettleTransfer]

ManualRefundTransfer

[Swagger:definition:json:ManualRefundTransfer]

[Swagger:definition:table:ManualRefundTransfer]

AddOn

[Swagger:definition:json:AddOn]

[Swagger:definition:table:AddOn]

SubscriptionAddOn

[Swagger:definition:json:SubscriptionAddOn]

[Swagger:definition:table:SubscriptionAddOn]

CreateAddOn

[Swagger:definition:json:CreateAddOn]

[Swagger:definition:table:CreateAddOn]

CreateSubscriptionAddOn

[Swagger:definition:json:CreateSubscriptionAddOn]

[Swagger:definition:table:CreateSubscriptionAddOn]

Discount

[Swagger:definition:json:Discount]

[Swagger:definition:table:Discount]

CreateDiscount

[Swagger:definition:json:CreateDiscount]

[Swagger:definition:table:CreateDiscount]

SubscriptionDiscount

[Swagger:definition:json:SubscriptionDiscount]

[Swagger:definition:table:SubscriptionDiscount]

CreateSubscriptionDiscount

[Swagger:definition:json:CreateSubscriptionDiscount]

[Swagger:definition:table:CreateSubscriptionDiscount]

DiscountSettings

[Swagger:definition:json:DiscountSettings]

[Swagger:definition:table:DiscountSettings]

Coupon

[Swagger:definition:json:Coupon]

[Swagger:definition:table:Coupon]

CreateCoupon

[Swagger:definition:json:CreateCoupon]

[Swagger:definition:table:CreateCoupon]

CouponRedemption

[Swagger:definition:json:CouponRedemption]

[Swagger:definition:table:CouponRedemption]

CancelSubscription

[Swagger:definition:json:CancelSubscription]

[Swagger:definition:table:CancelSubscription]

SubscriptionPeriodBalance

[Swagger:definition:json:SubscriptionPeriodBalance]

[Swagger:definition:table:SubscriptionPeriodBalance]

InvoiceBillingAddress

[Swagger:definition:json:InvoiceBillingAddress]

[Swagger:definition:table:InvoiceBillingAddress]

InvoiceShippingAddress

[Swagger:definition:json:InvoiceShippingAddress]

[Swagger:definition:table:InvoiceShippingAddress]

ChargeParameters

[Swagger:definition:json:ChargeParameters]

[Swagger:definition:table:ChargeParameters]

PaypalTransaction

[Swagger:definition:json:PaypalTransaction]

[Swagger:definition:table:PaypalTransaction]

ResursTransaction

[Swagger:definition:json:ResursTransaction]

[Swagger:definition:table:ResursTransaction]

KlarnaTransaction

[Swagger:definition:json:KlarnaTransaction]

[Swagger:definition:table:KlarnaTransaction]

ViabillTransaction

[Swagger:definition:json:ViabillTransaction]

[Swagger:definition:table:ViabillTransaction]

SwishTransaction

[Swagger:definition:json:SwishTransaction]

[Swagger:definition:table:SwishTransaction]

PayoutTransaction

[Swagger:definition:json:PayoutTransaction]

[Swagger:definition:table:PayoutTransaction]

SepaMandate

[Swagger:definition:json:SepaMandate]

[Swagger:definition:table:SepaMandate]

VippsRecurringSubscription

[Swagger:definition:json:VippsRecurringSubscription]

[Swagger:definition:table:VippsRecurringSubscription]

InvoiceConfiguration

[Swagger:definition:json:InvoiceConfiguration]

[Swagger:definition:table:InvoiceConfiguration]

InvoiceSequenceConfiguration

[Swagger:definition:json:InvoiceSequenceConfiguration]

[Swagger:definition:table:InvoiceSequenceConfiguration]