> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Accept and Record Payments in Nymble Commerce API

> Guide to accepting credit card payments, saving payment methods, completing hosted payment flows, and recording offline payments in Nymble Commerce.

Nymble Commerce supports card payments via hosted payment pages, saved payment methods (card-on-file), and offline payment recording — all tied to your invoices. Choose the approach that matches your storefront's PCI scope and your customers' preferences.

***

## Payment providers

Nymble Commerce integrates with **Authorize.Net** and **WorldPay (Vantiv)**. Your payment provider is configured once at the organization level via the [Integrations API](/guides/integrations). The payment endpoints behave identically regardless of the underlying processor, with the exception of the hosted payment flow, which is specific to WorldPay.

***

## Hosted payment flow (WorldPay)

Use the hosted payment flow when you want to accept card payments without handling raw card numbers in your application. WorldPay renders a secure, PCI-compliant form and Nymble Commerce receives the result via callback.

<Steps>
  <Step title="Create a transaction setup">
    Initiate a hosted payment session. Nymble Commerce returns the WorldPay transaction setup ID and the URL of the hosted payment page.

    ```http theme={null}
    POST https://api.achievemomentum.com/api/payments/worldpay/transaction-setup
    Authorization: Bearer {token}
    Content-Type: application/json

    {
      "customerNumber": "CUST-1042",
      "transactionAmount": 148.83,
      "applicationReturnUrl": "https://yourapp.com/payment/result",
      "isDefault": false,
      "marketCode": "Default"
    }
    ```

    **Request fields:**

    | Field                  | Type    | Required | Description                                                                           |
    | ---------------------- | ------- | -------- | ------------------------------------------------------------------------------------- |
    | `customerNumber`       | string  | Yes      | The customer's account number                                                         |
    | `transactionAmount`    | decimal | Yes      | Amount to charge. Use `0.00` to save a payment method only                            |
    | `applicationReturnUrl` | string  | Yes      | Your application URL that WorldPay redirects to after the customer completes the form |
    | `isDefault`            | boolean | No       | Whether to set this as the customer's default payment method                          |
    | `marketCode`           | string  | No       | Market code for the transaction (defaults to `"Default"`)                             |

    **Response**

    ```json theme={null}
    {
      "transactionSetupId": "txn_setup_f3c8a1b9",
      "hostedPaymentUrl": "https://hostedpayments.elementexpress.com/pay?token=abc123"
    }
    ```
  </Step>

  <Step title="Redirect your customer">
    Redirect the customer's browser to `hostedPaymentUrl`. WorldPay's secure page collects the card details — your application never handles the card number.
  </Step>

  <Step title="Receive the callback">
    After the customer submits their card, WorldPay calls back to Nymble Commerce with the transaction result. Nymble Commerce records the outcome automatically and then redirects the customer to your `applicationReturnUrl`.
  </Step>

  <Step title="Check payment status">
    Poll the invoice to confirm payment has been applied:

    ```http theme={null}
    GET https://api.achievemomentum.com/api/invoices/{invoiceId}
    Authorization: Bearer {token}
    ```

    Check the `paymentStatus` field in the response. When it reads `Paid`, the transaction is complete.
  </Step>
</Steps>

<Tip>
  Use the hosted payment flow whenever your application does not have PCI DSS scope — it's the fastest path to accepting cards safely. For repeat B2B customers who order frequently, consider offering card-on-file (saved payment methods) instead, so they can skip re-entering card details on every order.
</Tip>

***

## Saved payment methods

Saved payment methods let customers authorize a card once and reuse it for future orders without re-entering details. This flow is available for both Authorize.Net and WorldPay.

### Tokenize a card

```http theme={null}
POST https://api.achievemomentum.com/api/payments/payment-methods
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNumber": "CUST-1042",
  "emailAddress": "purchasing@acmeindustrial.com",
  "cardNumber": "4111111111111111",
  "expirationMonth": "09",
  "expirationYear": "2027",
  "cardCode": "123",
  "billingAddress": {
    "firstName": "Jane",
    "lastName": "Smith",
    "address1": "500 Commerce Drive",
    "city": "Austin",
    "state": "TX",
    "zipCode": "78701",
    "country": "US"
  },
  "isDefault": true
}
```

**Response**

```json theme={null}
{
  "paymentProfileId": "pp_7c1d4e99",
  "customerNumber": "CUST-1042",
  "cardType": "Visa",
  "lastFour": "1111",
  "expirationMonth": "09",
  "expirationYear": "2027",
  "isDefault": true
}
```

Pass the `paymentProfileId` in your checkout or payment requests to charge the stored card without prompting the customer for card details again.

### List saved payment methods

```http theme={null}
GET https://api.achievemomentum.com/api/payments/{customerNumber}/profiles
Authorization: Bearer {token}
```

**Response**

```json theme={null}
[
  {
    "paymentProfileId": "pp_7c1d4e99",
    "cardType": "Visa",
    "lastFour": "1111",
    "expirationMonth": 9,
    "expirationYear": 2027,
    "isDefault": true
  }
]
```

***

## Recording offline payments

For payments made outside the card network — wire transfers, ACH/EFT, or checks — record them directly against the invoice:

```http theme={null}
POST https://api.achievemomentum.com/api/invoices/{invoiceId}/payments/record
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 148.83,
  "paymentMethod": "Wire Transfer",
  "reference": "WIRE-REF-20240601-001",
  "paymentDate": "2024-06-01"
}
```

**Response**

```json theme={null}
{
  "paymentId": "pay_c9f02e41",
  "invoiceId": "inv_88a3bc10",
  "amount": 148.83,
  "paymentMethod": "Wire Transfer",
  "reference": "WIRE-REF-20240601-001",
  "paymentDate": "2024-06-01",
  "recordedAt": "2024-06-01T14:22:00Z"
}
```

***

## Completing a payment

After a successful hosted payment, call the complete endpoint to mark the invoice as paid. In most cases Nymble Commerce's callback handler calls this automatically, but you can also trigger it from your backend after receiving confirmation:

```http theme={null}
POST https://api.achievemomentum.com/api/invoices/{invoiceId}/payments/complete
Authorization: Bearer {token}
Content-Type: application/json

{
  "transactionId": "txn_provider_8812ab"
}
```

***

## Refunds

Issue a full or partial refund against a settled transaction:

```http theme={null}
POST https://api.achievemomentum.com/api/invoices/{invoiceId}/payments/refund
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 22.50,
  "reason": "Item returned — quantity adjustment"
}
```

<Warning>
  Refunds are sent directly to the payment provider and cannot be reversed through the API once submitted. Only refund transactions that have fully settled — processing a refund against a pending authorization will fail. Check with your provider on typical settlement windows (usually 1–2 business days).
</Warning>

***

## Invoice payment states

| Status          | Meaning                                                       |
| --------------- | ------------------------------------------------------------- |
| `Issued`        | Invoice created and sent; awaiting payment                    |
| `PartiallyPaid` | One or more payments recorded but the balance is not yet zero |
| `Paid`          | Invoice fully paid; balance is zero                           |
| `Voided`        | Invoice voided before payment; no longer collectible          |
| `Cancelled`     | Invoice cancelled; associated order was cancelled             |