# Introduction

Welcome to our developer hub. Here you will find comprehensive guides and documentation to help you start working with DebitDirect, as well as support if you get stuck. Let’s get started!

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><img src="https://159965433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1I2W9IsRgBGDPAkwvjzU%2Fuploads%2FMiBkRCIXEHkYrPmyOGSX%2Fundraw_learning_re_32qv.svg?alt=media&amp;token=9a218dc2-42e9-47c2-8fd8-4245f9a77798" alt=""><br></td><td></td><td></td></tr><tr><td><img src="https://159965433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1I2W9IsRgBGDPAkwvjzU%2Fuploads%2FP5hE624yjQPz6IUveBJJ%2Fundraw_static_website_re_x70h.svg?alt=media&amp;token=71815f9a-1f49-45d5-b48d-9bb166516f14" alt=""><br></td><td></td><td></td></tr><tr><td><img src="https://159965433-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1I2W9IsRgBGDPAkwvjzU%2Fuploads%2Fz2TjtqI8ao8Wy1Tm81Ia%2Fundraw_proud_coder_re_exuy.svg?alt=media&amp;token=d969183a-92f6-4729-9961-842422ec05c7" alt=""><br></td><td></td><td></td></tr><tr><td><p><strong>Product documentation</strong></p><p>Read <a href="https://docs.debitdirect.io">the docs</a></p></td><td></td><td></td></tr><tr><td><p><strong>API Reference</strong></p><p>Learn <a href="/welcome">our API</a></p></td><td></td><td></td></tr><tr><td><p><strong>Accelerate development</strong></p><p>Get <a href="https://www.nuget.org/packages/DebitDirect.Sdk">an SDK</a></p></td><td></td><td></td></tr></tbody></table>


# Welcome

Our API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts [JSON-encoded](http://www.json.org/) request bodies, returns [JSON-encoded](http://www.json.org/) responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the API for testing, which doesn't affect your live data or interact with the payment schemes. The API key you use to authenticate the request determines whether the request is live mode or test mode.

Our API doesn't support bulk updates. You can work on only one object per request.

{% hint style="info" %}
<https://api.debitdirect.io>
{% endhint %}


# Authentication

Our API use API keys to authenticate requests. You can manage your API keys using the API.

Our secret keys have the prefix `sk_`. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without authentication will also fail.

```sh
curl https://api.debitdirect.io/me \
  -u sk_ddMfjeC39HqLyjWDarjtT1zdp7dc: \
  --header "x-version: 4.0"
```


# Errors

Our API uses conventional HTTP response codes to indicate the 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 failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the `5xx` range indicate an error with our servers (these are rare).

Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.

## Error code

Attributes are returned as JSON objects, examplified as follows:

```json
{
    "title": "",
    "type" : "",
    "traceId" : ""
}
```

### Attributes

**title** (string)\
A human-readable message providing more details about the error.&#x20;

**traceId** (string)\
A traceable id which corrolates with our logging records.

**type** (string)\
The type of error returned.


# Idempotency

The API supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

To perform an idempotent request, provide an additional `Idempotency-Key: <key>` header to the request.

Our idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including `500` errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 255 characters long.

Keys are eligible to be removed from the system automatically after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

All `POST` requests accept idempotency keys. Sending idempotency keys in `GET` and `DELETE` requests has no effect and should be avoided, as these requests are idempotent by definition.


# Pagination


# Metadata


# Versioning


# Traceability


# Limitations

## Throttling


# API reference


# Agreements


# Agreement Object

```json
{
    "handle": "am_a004X9KLljBVOOwoPNNJoEPp",
    "scheme": "nets-ls",
    "test": true,
    "state": "Active",
    "metaData": {
        "CreditorNumber": "12345",
        "CvrNumber": "12345678"
    }
}
```

### Attributes

**handle** (string)\
A unique handle of the agreement.

**scheme** (string)\
Name of the scheme associated to the agreement. Metadata will apply specific to the scheme.

**test** (boolean)\
If true the agreement is used to test purpose. All associated payments will not occur in real time.

**state** (string)\
Active. The agreement is active.\
InActive. The agreement has been terminated.

**metaData** (object)\
An object specifying data of the given scheme. See *scheme* attribute.


# List agreements

## List agreements

<mark style="color:blue;">`GET`</mark> `https://api.debitdirect.io/agreements`

#### Query Parameters

| Name     | Type | Description |
| -------- | ---- | ----------- |
| page     | int  |             |
| pagesize | int  |             |

{% tabs %}
{% tab title="200: OK Paged collection of agreement." %}

```json
{
    "results" : [
    ],
    "paging" : {
        "totalCount" : 0,
        "totalPages" : 0,
        "currentPage" : 0,
        "results" : 0
    },
    "links" : {
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}
{% endtabs %}


# Get agreement

## List agreements

<mark style="color:blue;">`GET`</mark> `https://api.debitdirect.io/agreements/{handle}`

#### Path Parameters

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| handle<mark style="color:red;">\*</mark> | String |             |

#### Query Parameters

| Name     | Type | Description |
| -------- | ---- | ----------- |
| page     | int  |             |
| pagesize | int  |             |

{% tabs %}
{% tab title="200: OK Paged collection of agreement." %}

```json
{
    "handle" : "string"
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}


# Get template

Retrieve schema template.

`HEAD` `https://api.debitdirect.io/agreements`

Retrieve a metaData collection object to be used when [creating an agreement](/api/api-reference/agreements/create-agreement).

#### Request Body

| Name                                     | Type   | Description                              |
| ---------------------------------------- | ------ | ---------------------------------------- |
| scheme<mark style="color:red;">\*</mark> | String | Name of supported scheme. Ex. 'nets-ls'. |

{% tabs %}
{% tab title="200: OK MetaData template to use for creating an agreement." %}

```json
{
    "metaData": {
        "key" : "value"
    }
}
```

{% endtab %}
{% endtabs %}


# Create agreement

<mark style="color:green;">`POST`</mark> `https://api.debitdirect.io/agreements`

#### Request Body

| Name                                     | Type       | Description                                                                                                                                              |
| ---------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| scheme<mark style="color:red;">\*</mark> | String     | Name of scheme. i.e. 'nets-ls'                                                                                                                           |
| meta<mark style="color:red;">\*</mark>   | Collection | Key-value data for the given scheme. Use [HEAD Get template](/api/api-reference/agreements/get-template) request to get a collection for a given scheme. |
| test                                     | Boolean    | Default to false. If true, any associated mandate and payment will be test only.                                                                         |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "handle": "am_xxxxxxxxxxxxxxxxxx",
    "scheme": "nets-ls",
    "test": true,
    "state": "Pending",
    "metaData": {
        "CreditorNumber": "12345",
        "CvrNumber": "12345678"
    }
}
```

{% endtab %}
{% endtabs %}


# ApiKeys


# ApiKey object


# Customers


# Customer object


# List customers


# Get customer


# Mandates

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Mandates/{handle}" method="get" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Mandates" method="get" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}


# Mandate object


# Payments

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Payments/{handle}" method="get" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Payments/{handle}" method="delete" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Payments" method="get" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Payments" method="post" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}


# Cancel

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Payments/{handle}/cancel" method="put" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}


# Webhooks

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Webhooks" method="get" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Webhooks" method="post" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Webhooks/{handle}" method="delete" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}


# Merchants


# Me

{% openapi src="<https://api.debitdirect.io/swagger/v1/swagger.json>" path="/Merchants/me" method="get" %}
<https://api.debitdirect.io/swagger/v1/swagger.json>
{% endopenapi %}


# Events