Accept and Record Payments in Nymble Commerce API

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. 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.

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.

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

{
  "transactionSetupId": "txn_setup_f3c8a1b9",
  "hostedPaymentUrl": "https://hostedpayments.elementexpress.com/pay?token=abc123"
}

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.

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.

Check payment status

Poll the invoice to confirm payment has been applied:

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.

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.

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

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

{
  "customerNumber": "CUST-1042",
  "emailAddress": "[email protected]",
  "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

{
  "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

GET https://api.achievemomentum.com/api/payments/{customerNumber}/profiles
Authorization: Bearer {token}

Response

[
  {
    "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:

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

{
  "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:

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:

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"
}

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).

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

Get Started

Core Concepts

Guides

Help

Accept and Record Payments in Nymble Commerce API

Payment providers

Hosted payment flow (WorldPay)

Saved payment methods

Tokenize a card

List saved payment methods

Recording offline payments

Completing a payment

Refunds

Invoice payment states

​Payment providers

​Hosted payment flow (WorldPay)

​Saved payment methods

​Tokenize a card

​List saved payment methods

​Recording offline payments

​Completing a payment

​Refunds

​Invoice payment states

Payment providers

Hosted payment flow (WorldPay)

Saved payment methods

Tokenize a card

List saved payment methods

Recording offline payments

Completing a payment

Refunds

Invoice payment states