# Connect your PayNow store

> Connect your own PayNow store to your organization, and manage its subscriptions, gift cards and affiliates.

Source: https://www.coritan.com/docs/organizations/billing/paynow/

In the dashboard:

- /dashboard/organizations/…/billing/paynow: https://www.coritan.com/dashboard/organizations

PayNow is a payment provider that acts as merchant of record for the stores it runs. When your organization bills with **Own gateway** or **Hybrid**, Coritan charges your customers through your own PayNow store, and the money reaches you through PayNow rather than through Coritan's payouts. The **PayNow** section of the **Billing** tab holds the store connection and, once the store is connected, its gift cards, affiliate links and subscriptions.

## Before you begin

- You need a PayNow store, its store ID and an API key for it from the PayNow dashboard.
- To connect the store or change its connection, you need the owner or admin role. Billing members can see the connection and manage the gift cards, affiliate links and subscriptions.

## How your billing mode uses the store

| Billing mode | How customers pay their invoices |
| --- | --- |
| **Platform merchant of record** | Through Coritan's payment gateways. A connected store is not used. |
| **Hybrid** | Through your PayNow store while its connection is active, and through Coritan's payment gateways when it is not. |
| **Own gateway** | Through your PayNow store only. Checkout fails while no active store is connected. |

## Connect the store

1. In the [dashboard](https://www.coritan.com/dashboard/organizations), open the organization, then **Billing**, then **PayNow**.
2. Select **Connect store**, or **Edit connection** when a store is already saved.
3. Enter the **Store ID** and the **API key**. The key is write-only: when you edit the connection later, leave it empty to keep the stored one.
4. Leave **Webhook secret** empty, or paste the secret of a webhook you created in PayNow (see the next section).
5. To have PayNow pay your share of each payment into a PayNow payout account, enter its **Payout account ID**. **Platform fee (basis points)** is the part PayNow keeps back for Coritan: 600 means 6%. Leave it empty to use your organization's platform fee rate. Once a fee is stored, you can change it but not clear it.
6. Set **Store mode** to match how you bill, and choose the **Organization billing mode**. The billing mode changes how Coritan charges every future invoice.
7. Keep **Connection active** ticked, then select **Save connection**.

The card now shows **Connected**. Coritan does not test the API key when you save it, so the first checkout shows whether the store takes payments.

To stop charging through the store without losing its credentials, edit the connection, untick **Connection active** and save. The card then shows **Disabled**.

## Check the webhook

Coritan marks an invoice paid when PayNow reports that the payment went through, so your store needs a webhook that points at Coritan. After you save the connection, look at the **Webhook secret** row. When it reads "Stored", the webhook is in place. Otherwise, create it in PayNow:

1. In the PayNow dashboard, add a webhook with the URL `https://api.coritan.com/api/v1/webhooks/orgs/{org_id}/paynow`, where `{org_id}` is your organization's numeric ID. The API returns it as `id` from `GET /api/v1/orgs/acme`.
2. Subscribe it to these events: `OnOrderCompleted`, `OnPaymentCompleted`, `OnPaymentFailed`, `OnRefund`, `OnChargeback`, `OnChargebackClosed`, `OnSubscriptionRenewed` and `OnSubscriptionCanceled`.
3. Copy the webhook's secret into **Webhook secret** in the Coritan dashboard, then select **Save connection**.

Coritan refuses a webhook whose signature does not match the secret.

## Manage gift cards, affiliate links and subscriptions

These cards appear once the store is connected and its connection is active. They read and change your PayNow store directly.

To create a gift card:

1. Under **Gift cards**, select **New gift card**.
2. Enter the **Balance** and the **Currency**. Leave **Code** empty to have one generated.
3. Select **Create gift card**.

To create an affiliate link:

1. Under **Affiliate links**, select **New affiliate link**.
2. Enter the **Code** customers type at checkout and the **Commission (%)** it pays. In **Customer ID**, enter the customer who owns the code, or leave it empty for your brand.
3. Select **Create affiliate link**.

The list shows how many **Uses** each code has had and the **Revenue** it brought in.

To cancel a subscription, select **Cancel** in its row under **Subscriptions**, then **Cancel subscription**.

## Troubleshooting

"Organization PayNow store is not configured"
: Your billing mode is **Own gateway** and no active store is connected. Connect the store, tick **Connection active**, or switch the billing mode.

Customers paid but their invoices stay unpaid
: PayNow is not reaching Coritan. Follow the steps in [Check the webhook](#check-the-webhook).

A message that starts with "Failed to"
: PayNow refused the request. A `401` or `403` in the message means the API key is wrong or cannot do this; enter a new key under **Edit connection**.

## Related

- [Organization billing](/docs/organizations/billing/)
- [How organizations work](/docs/organizations/how-organizations-work/)
- [Manage customer invoices](/docs/organizations/billing/invoices/)

## With the API

Read the connection. This takes the owner, admin or billing role:

```bash
curl "https://api.coritan.com/api/v1/orgs/acme/billing/paynow" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

The answer has `billing_mode`, `configured` (`true` when the connection is active and has a store ID and an API key), `is_active`, `mode`, `store_id`, `has_api_key`, `has_webhook_secret`, `payout_id` and `platform_fee_bps`. It never returns the key or the secret.

Save the connection. This takes the owner or admin role:

```bash
curl -X PUT "https://api.coritan.com/api/v1/orgs/acme/billing/paynow" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "358129046",
    "api_key": "pnapi_example",
    "mode": "own_gateway",
    "is_active": true,
    "billing_mode": "own_gateway"
  }'
```

The body also takes `webhook_secret`, `payout_id` and `platform_fee_bps`. A credential you leave out keeps its stored value. Send `mode` and `is_active` every time: when they are missing, the connection becomes `own_gateway` and active. `billing_mode` takes `platform_mor`, `own_gateway` or `hybrid`. The answer is the connection as above, with `webhook_url`, the path of the webhook that PayNow calls.

The store's features take the owner, admin or billing role, and answer `503` with "PayNow not available" when there is no store to ask:

| Operation | What it does |
| --- | --- |
| `GET /api/v1/orgs/acme/billing/paynow/giftcards` | Lists the gift cards as `giftcards`. |
| `POST /api/v1/orgs/acme/billing/paynow/giftcards` | Creates a gift card. |
| `GET /api/v1/orgs/acme/billing/paynow/affiliates` | Lists the affiliate links as `affiliates`. |
| `POST /api/v1/orgs/acme/billing/paynow/affiliates` | Creates an affiliate link. |
| `GET /api/v1/orgs/acme/billing/paynow/subscriptions` | Lists the subscriptions as `subscriptions`. |
| `POST /api/v1/orgs/acme/billing/paynow/subscriptions/{subscription_id}/cancel` | Cancels a subscription. |

Coritan passes the body of a create to PayNow's management API as it is, and returns PayNow's answer. The dashboard sends `balance` in cents, `currency` and an optional `code` for a gift card, and `code`, `commission_percent` and an optional `customer_id` for an affiliate link. When PayNow refuses a list, the answer is `502`; when it refuses a create or a cancel, it is `400`. Both carry PayNow's reason.

## API

- `GET /api/v1/orgs/{org_slug}/billing/paynow`: Get paynow status (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-get-api-v1-orgs-org-slug-billing-paynow)
- `PUT /api/v1/orgs/{org_slug}/billing/paynow`: Save org-owned PayNow store credentials (owngateway / hybrid) (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-put-api-v1-orgs-org-slug-billing-paynow)
- `GET /api/v1/orgs/{org_slug}/billing/paynow/affiliates`: List paynow affiliates (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-get-api-v1-orgs-org-slug-billing-paynow-affiliates)
- `POST /api/v1/orgs/{org_slug}/billing/paynow/affiliates`: Create paynow affiliate (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-post-api-v1-orgs-org-slug-billing-paynow-affiliates)
- `GET /api/v1/orgs/{org_slug}/billing/paynow/giftcards`: List paynow giftcards (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-get-api-v1-orgs-org-slug-billing-paynow-giftcards)
- `POST /api/v1/orgs/{org_slug}/billing/paynow/giftcards`: Create paynow giftcard (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-post-api-v1-orgs-org-slug-billing-paynow-giftcards)
- `GET /api/v1/orgs/{org_slug}/billing/paynow/subscriptions`: List paynow subscriptions (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-get-api-v1-orgs-org-slug-billing-paynow-subscriptions)
- `POST /api/v1/orgs/{org_slug}/billing/paynow/subscriptions/{subscription_id}/cancel`: Cancel paynow subscription (https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/#op-post-api-v1-orgs-org-slug-billing-paynow-subscriptions-subscription-id-cancel)