# Store payments API

> Reference for the 5 public v1 operations of the Store payments API, generated from the OpenAPI spec.

Source: https://docs.nexafone.so/v1/api/payments/

Generated from `api/openapi.public.yaml`, the same spec the API serves. Try these operations in the [API console](/v1/api/console/); errors are [Problem Details](/v1/errors/).

## Get the store's PayPoint connection

`GET /api/v1/workspaces/{workspaceId}/payments/paypoint`

Whether the store's own PayPoint key is saved (never the key) and the wallets customers may pay with.

| | |
| --- | --- |
| Operation id | `getStorePayPoint` |
| Authentication | A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores. |
| Permission (key scope) | `payments:manage` |
| Plan feature | `commerce.payments` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | `application/json`: [StorePayPointBody](/v1/api/schemas/#storepaypointbody) |
| default | Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
curl -X GET "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/payments/paypoint" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"
```

## Save the store's PayPoint key

`PUT /api/v1/workspaces/{workspaceId}/payments/paypoint`

Replaces any saved key. The key is write-only: no response, now or later, contains more than its last four characters. The workspace's owners and payment managers are told. A dashboard session needs a sign-in within the last 10 minutes; otherwise it answers 401 reauthentication_required. An SDK session is refused with 403 dashboard_sign_in_required.

| | |
| --- | --- |
| Operation id | `saveStorePayPointKey` |
| Authentication | A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores. |
| Permission (key scope) | `payments:manage` |
| Plan feature | `commerce.payments` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |

### Request body

`application/json`: [StorePayPointKeyBody](/v1/api/schemas/#storepaypointkeybody)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `apiKey` | string | yes | The store's own PayPoint API key. It is stored encrypted and never returned. (min length 1, max length 512) |
| `merchantId` | string | yes | The store's PayPoint merchant id (min length 1, max length 100, pattern `^[A-Za-z0-9_.-]+$`) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | `application/json`: [StorePayPointKeySavedBody](/v1/api/schemas/#storepaypointkeysavedbody) |
| 401 | Unauthorized | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 503 | Service Unavailable | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
curl -X PUT "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/payments/paypoint" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"string","merchantId":"string"}'
```

## Remove the store's PayPoint key

`DELETE /api/v1/workspaces/{workspaceId}/payments/paypoint`

The workspace's owners and payment managers are told. A dashboard session needs a sign-in within the last 10 minutes; otherwise it answers 401 reauthentication_required. An SDK session is refused with 403 dashboard_sign_in_required.

| | |
| --- | --- |
| Operation id | `deleteStorePayPointKey` |
| Authentication | A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores. |
| Permission (key scope) | `payments:manage` |
| Plan feature | `commerce.payments` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 204 | No Content |  |
| 401 | Unauthorized | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
curl -X DELETE "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/payments/paypoint" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"
```

## Check the store's PayPoint key with PayPoint

`POST /api/v1/workspaces/{workspaceId}/payments/paypoint/test`

Asks PayPoint whether it accepts the saved key, without charging anyone.

| | |
| --- | --- |
| Operation id | `testStorePayPointKey` |
| Authentication | A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores. |
| Permission (key scope) | `payments:manage` |
| Plan feature | `commerce.payments` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | `application/json`: [StorePayPointKeyTestBody](/v1/api/schemas/#storepaypointkeytestbody) |
| 404 | Not Found | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 503 | Service Unavailable | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
curl -X POST "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/payments/paypoint/test" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY"
```

## Choose the wallets customers may pay the store with

`PUT /api/v1/workspaces/{workspaceId}/payments/paypoint/wallets`

A dashboard session needs a sign-in within the last 10 minutes; otherwise it answers 401 reauthentication_required. An SDK session is refused with 403 dashboard_sign_in_required.

| | |
| --- | --- |
| Operation id | `setStorePayPointWallets` |
| Authentication | A secret key (`sk_live_…` or `sk_test_…`), an SDK session token (`sdk_…`), or a secret partner key for one of the partner’s stores. |
| Permission (key scope) | `payments:manage` |
| Plan feature | `commerce.payments` |

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | path | string | yes | Workspace id (UUID) |

### Request body

`application/json`: [StorePayPointWalletsBody](/v1/api/schemas/#storepaypointwalletsbody)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `wallets` | array of `"evc_plus"` \| `"zaad"` \| `"sahal"` \| `"jeeb"` \| `"edahab"` \| `"premier_wallet"` | yes | The wallets customers may pay with in the WhatsApp checkout (max 6 items) |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | `application/json`: [StorePayPointBody](/v1/api/schemas/#storepaypointbody) |
| 401 | Unauthorized | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 422 | Unprocessable Entity | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |
| 500 | Internal Server Error | `application/problem+json`: [Problem](/v1/api/schemas/#problem) |

### Example

```bash
curl -X PUT "https://api.nexafone.so/api/v1/workspaces/{workspaceId}/payments/paypoint/wallets" \
  -H "Authorization: Bearer $NEXAFON_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallets":["evc_plus"]}'
```