# Integration quick start (/docs/direct-debit/integration-quick-start)

## Overview [#overview]

The Precium Debit Order API enables you to generate ad-hoc or recurring debit order payments and collections. This guide will help you make your first API call.

## Prerequisites [#prerequisites]

Before you begin, you will need:

1. **API Credentials**: Contact our sales team at support@precium.com to request your sandbox username and password
2. **Postman or HTTP Client**: For testing API requests
3. **Understanding of South African debit orders**: Familiarity with EFT and DebiCheck payment instruments


## Step 1: Obtain Access Token [step] [#step-1-obtain-access-token-step]

All API requests require a Bearer token. Generate one using OAuth 2.0 Client Credentials flow:

```bash
curl -X POST https://dev-payce.auth.eu-west-1.amazoncognito.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -d "grant_type=client_credentials"
```

**Response:**

```json
{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 86400,
  "token_type": "Bearer"
}
```

<Callout type="info">
Note: Access tokens expire every 24 hours.
</Callout>

## Step 2: Get Your Merchant Profile [step] [#step-2-get-your-merchant-profile-step]

Retrieve your merchant profile to obtain the required configuration values:

```bash
curl -X GET https://dev.api.revio.co.za/v2/merchantprofile/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json
[
  {
    "id": "24",
    "profileCode": "TEST1",
    "abbreviatedName": "TESTMERCH1",
    "accountNumber": "12345678",
    "branchCode": "051001",
    "name": "TEST MERCHANT 1",
    "instruments": ["EFTONEDAY", "EFTTWODAY", "EFTSAMEDAY", "DEBICHECK"],
    "currency": "ZAR",
    "entryClass": "21"
  }
]
```

Store these values—you'll need them for subsequent API calls:

- `profileCode`
- `abbreviatedName`
- `accountNumber` (creditor account)
- `branchCode` (creditor branch)
- `name` (creditor name)

## Step 3: Create Your First EFT Mandate [step] [#step-3-create-your-first-eft-mandate-step]

Create a mandate to authorise future collections from a customer:

```bash
curl -X POST https://dev.api.revio.co.za/v2/mandate/eft/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultServiceType": "ONEDAY",
    "profileCode": "TEST1",
    "abbreviatedName": "TESTMERCH1",
    "contractReference": "CONTRACT001",
    "debtor": {
      "accountNumber": "010553922",
      "accountType": "CURRENT",
      "bank": "ABSA",
      "branchCode": "632005",
      "firstName": "John",
      "lastName": "Smith",
      "identification": {
        "emailAddress": "john@example.com",
        "idNumber": "0001010000006",
        "phoneNumber": "+27-123456789"
      }
    },
    "creditor": {
      "accountNumber": "12345678",
      "accountType": "CURRENT",
      "branchCode": "051001",
      "name": "TEST MERCHANT 1",
      "bank": "STANDARDBANK",
      "phoneNumber": "+27-615333440",
      "emailAddress": "merchant@test.com"
    },
    "frequency": "MONTHLY",
    "collectionDay": 15,
    "amountCents": 10000,
    "currency": "ZAR",
    "entryClass": "21"
  }'
```

**Response:**

```json
{
  "id": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
  "status": "ACTIVE",
  "contractReference": "CONTRACT001",
  ...
}
```

## Step 4: Create a Collection [step] [#step-4-create-a-collection-step]

Use the mandate ID to create a collection:

```bash
curl -X POST https://dev.api.revio.co.za/v2/collection/eft/from_mandate/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mandateId": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
    "collectionDate": "2024-02-15T00:00:00.000Z",
    "amountCents": 10000,
    "serviceType": "ONEDAY"
  }'
```

**Response:**

```json
{
  "id": "63d94be3-1faf-428b-89f3-bc5271be8015",
  "status": "PENDING",
  ...
}
```

## Step 5: Check Collection Status [step] [#step-5-check-collection-status-step]

Monitor the collection status:

```bash
curl -X GET https://dev.api.revio.co.za/v2/collection/eft/63d94be3-1faf-428b-89f3-bc5271be8015/status/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```


## Quick Reference [#quick-reference]

| Action | Endpoint | Method |
|---|---|---|
| Get Token | `/oauth2/token` | POST |
| Get Merchant Profile | `/v2/merchantprofile/` | GET |
| Create EFT Mandate | `/v2/mandate/eft/` | POST |
| Create DebiCheck Mandate | `/v2/mandate/debicheck/` | POST |
| Create EFT Collection | `/v2/collection/eft/from_mandate/` | POST |
| Create DebiCheck Collection | `/v2/collection/debicheck/from_mandate` | POST |
| Create EFT Payment | `/v2/payment/eft` | POST |

## Next Steps [#next-steps]

- Authentication - Learn about token management
- EFT Debit Orders - Detailed EFT mandate and collection guide
- DebiCheck - Authenticated debit order collections
- Testing - Test scenarios and mock bank simulation

## Resources [#resources]

- **Postman Collection**: Available for download from the Precium technical reference documentation