Payments API Reference for Nymble Commerce

The Payments API handles card payment collection through hosted pages and saved payment methods (card-on-file). Nymble Commerce integrates with Authorize.Net and WorldPay as payment providers — your organization’s active provider is configured in your tenant settings and used automatically unless you specify otherwise.

Raw card numbers are never sent to or stored by Nymble Commerce. All card data is submitted directly from your customer’s browser to the payment provider’s hosted page. Nymble Commerce receives only a token and masked card details after the transaction is complete.

Hosted payment flow

The standard card payment flow uses a provider-hosted page so that your application never handles raw card data.

Initiate a transaction setup

Call POST /api/payments/worldpay/transaction-setup with the customer number, the invoice amount, and a return URL. Nymble Commerce creates a transaction setup with the payment provider and returns a HostedPaymentUrl and a TransactionSetupId.

Redirect the customer

Redirect the customer’s browser to the HostedPaymentUrl. The payment provider renders a secure, hosted payment form where the customer enters their card details.

Customer submits payment

The customer completes the payment form on the provider’s hosted page. The provider processes the transaction directly.

Provider posts the callback

After the transaction completes (success or failure), the provider posts the result to Nymble Commerce’s callback endpoint (POST /api/payments/worldpay/callback). Nymble Commerce records the payment against the invoice and updates the invoice status accordingly.

Customer is redirected back

The provider redirects the customer to the ApplicationReturnUrl you supplied in step 1. You can use this URL to display a payment confirmation or error message in your application.

The TransactionSetupId is valid for 10 minutes. If the customer does not complete the payment within that window, initiate a new transaction setup.

Saved payment methods

You can save a customer’s card as a payment method (card-on-file) to enable one-click checkout and recurring billing. Nymble Commerce stores only the payment provider’s token and masked card details — never the raw card number.

For Authorize.Net: you can save a card directly by posting card details to POST /api/payments/payment-methods. Authorize.Net tokenizes the card and returns a PaymentProfileId.
For WorldPay: saving a card requires a redirect to a hosted page. POST /api/payments/payment-methods returns a RequiresRedirect: true response with a RedirectUrl. Send the customer to that URL to complete tokenization.

The payment method object

string

Internal Nymble Commerce ID for this saved payment method.

customerNumber

string

The customer account this payment method belongs to.

paymentProfileId

string

The payment provider’s identifier for this saved card profile. Use this ID when recording payments against an invoice.

customerProfileId

string

The payment provider’s identifier for the customer profile that owns this payment method.

maskedCardNumber

string

The masked card number (e.g. XXXX1234).

cardType

string

Card brand (e.g. Visa, Mastercard, AmericanExpress, Discover).

expirationDate

string

Card expiry in MMYY or MM/YYYY format, as returned by the provider.

expMonth

integer

Expiry month as an integer (1–12).

expYear

integer

Expiry year as a four-digit integer.

billingAddress

object

The billing address associated with this card.

Show billingAddress fields

isDefault

boolean

Whether this is the customer’s default payment method.

paymentProvider

string

The payment provider that issued this profile token (e.g. AuthorizeNet, WorldPay).

active

boolean

Whether this payment method is active.

networkTransactionId

string

Network transaction ID from the provider, used for subsequent card-on-file transactions.

Endpoints

Initiate a hosted payment session

Creates a WorldPay transaction setup and returns a URL to which you redirect the customer to complete payment. This is the first step in the hosted payment flow.

Request body

customerNumber

string

required

The account number of the customer making the payment. Used to associate the transaction and any saved card with the correct customer profile.

transactionAmount

number

required

The amount to charge. Pass 0.00 if you are using this setup only to save a payment method without charging the customer.

applicationReturnUrl

string

required

The URL in your application to redirect the customer to after payment completes (whether successful or failed). The provider appends the transaction result as query parameters.

marketCode

string

WorldPay market code. Defaults to Default. Contact your Nymble Commerce account team if you need a custom market code.

isDefault

boolean

If the customer saves their card during this transaction, whether to set it as their default payment method. Defaults to false.

Example request

curl -X POST https://api.achievemomentum.com/api/payments/worldpay/transaction-setup \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "CUST-1042",
    "transactionAmount": 479.30,
    "applicationReturnUrl": "https://yourapp.com/checkout/payment-result",
    "isDefault": false
  }'

Response

transactionSetupId

string

The transaction setup ID from the payment provider. Valid for 10 minutes. Store this to correlate the provider callback with the payment attempt.

hostedPaymentUrl

string

The complete URL to redirect the customer to. This URL contains the setup ID and provider-specific parameters — do not modify it.

Example response

{
  "transactionSetupId": "ABC123DEF456GHI789",
  "hostedPaymentUrl": "https://certtransaction.hostedpayments.com/?TransactionSetupID=ABC123DEF456GHI789"
}

After receiving this response, redirect the customer’s browser to hostedPaymentUrl:

// Example: redirect in a browser context
window.location.href = response.hostedPaymentUrl;

Get saved payment methods for a customer

Retrieves all saved payment methods (cards on file) for a customer. Use the returned paymentProfileId values when recording a payment against an invoice via POST /api/invoices/{invoiceId}/payments.

Path parameters

customerNumber

string

required

The customer’s account number.

Example request

curl https://api.achievemomentum.com/api/payments/CUST-1042/profiles \
  -H "Authorization: Bearer <token>"

Response

Returns 200 OK with an array of payment method objects.

[
  {
    "id": "pm-uuid-001",
    "customerNumber": "CUST-1042",
    "paymentProfileId": "1234567890",
    "customerProfileId": "9876543210",
    "maskedCardNumber": "XXXX4242",
    "cardType": "Visa",
    "expirationDate": "1226",
    "expMonth": 12,
    "expYear": 2026,
    "billingAddress": {
      "firstName": "Alex",
      "lastName": "Chen",
      "company": "Brightfield Supply Co.",
      "address1": "300 Commerce Blvd",
      "city": "Portland",
      "state": "OR",
      "zipCode": "97201",
      "country": "US"
    },
    "isDefault": true,
    "paymentProvider": "AuthorizeNet",
    "active": true
  },
  {
    "id": "pm-uuid-002",
    "customerNumber": "CUST-1042",
    "paymentProfileId": "1234567891",
    "customerProfileId": "9876543210",
    "maskedCardNumber": "XXXX1881",
    "cardType": "Mastercard",
    "expirationDate": "0827",
    "expMonth": 8,
    "expYear": 2027,
    "billingAddress": {
      "firstName": "Alex",
      "lastName": "Chen",
      "company": "Brightfield Supply Co.",
      "address1": "300 Commerce Blvd",
      "city": "Portland",
      "state": "OR",
      "zipCode": "97201",
      "country": "US"
    },
    "isDefault": false,
    "paymentProvider": "AuthorizeNet",
    "active": true
  }
]

Save a payment method

Saves a payment method (tokenizes a card) for a customer. The behaviour differs by payment provider:

Authorize.Net: card details are submitted directly in the request body. Authorize.Net tokenizes the card server-side and returns the saved payment method immediately. RequiresRedirect is false.
WorldPay: a direct card submission is not supported. The response contains RequiresRedirect: true and a RedirectUrl. Redirect the customer to that URL to enter their card details on the WorldPay hosted page.

Only use the direct card submission flow (Authorize.Net) from a server-side integration where you control the PCI scope. For customer-facing web applications, prefer the hosted payment flow via POST /api/payments/worldpay/transaction-setup to avoid handling raw card data.

Request body

customerNumber

string

required

The account number of the customer whose card is being saved.

emailAddress

string

required

Customer’s email address, used to create or match the customer profile with the payment provider.

cardNumber

string

required

Full card number. Only used for Authorize.Net (direct flow). For WorldPay, any value is acceptable — the redirect flow ignores this field.

expirationMonth

string

required

Two-digit expiry month (e.g. 09).

expirationYear

string

required

Four-digit expiry year (e.g. 2027).

cardCode

string

required

Card security code (CVV/CVC). Required for Authorize.Net. Not stored after tokenization.

billingAddress

object

required

The billing address for the card.

Show billingAddress fields

isDefault

boolean

Set to true to make this the customer’s default payment method. Defaults to false.

paymentProvider

string

Specify which payment provider to use (AuthorizeNet or WorldPay). When omitted, uses the organization’s default active provider.

appUrl

string

For WorldPay (redirect flow) — the URL in your application to return the customer to after they save their card. Defaults to http://localhost:3000/payment-success when omitted.

Example request (Authorize.Net — direct)

curl -X POST https://api.achievemomentum.com/api/payments/payment-methods \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "CUST-1042",
    "emailAddress": "[email protected]",
    "cardNumber": "4111111111111111",
    "expirationMonth": "12",
    "expirationYear": "2027",
    "cardCode": "123",
    "billingAddress": {
      "firstName": "Alex",
      "lastName": "Chen",
      "company": "Brightfield Supply Co.",
      "address1": "300 Commerce Blvd",
      "city": "Portland",
      "state": "OR",
      "zipCode": "97201",
      "country": "US"
    },
    "isDefault": true,
    "paymentProvider": "AuthorizeNet"
  }'

Example request (WorldPay — redirect)

curl -X POST https://api.achievemomentum.com/api/payments/payment-methods \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "CUST-1042",
    "emailAddress": "[email protected]",
    "cardNumber": "",
    "expirationMonth": "01",
    "expirationYear": "2030",
    "cardCode": "",
    "billingAddress": {
      "firstName": "Alex",
      "lastName": "Chen",
      "address1": "300 Commerce Blvd",
      "city": "Portland",
      "state": "OR",
      "zipCode": "97201",
      "country": "US"
    },
    "isDefault": false,
    "paymentProvider": "WorldPay",
    "appUrl": "https://yourapp.com/payment-methods/saved"
  }'

Response

requiresRedirect

boolean

false for Authorize.Net (card saved immediately). true for WorldPay (customer must complete a hosted page).

redirectUrl

string

The URL to redirect the customer to (WorldPay only). null for Authorize.Net.

provider

string

The payment provider used for this request.

paymentMethod

object

The saved payment method (Authorize.Net only, when requiresRedirect is false). See the payment method object for full field details.

Example response (Authorize.Net — direct)

{
  "requiresRedirect": false,
  "redirectUrl": null,
  "provider": "AuthorizeNet",
  "paymentMethod": {
    "id": "pm-uuid-003",
    "customerNumber": "CUST-1042",
    "paymentProfileId": "1234567892",
    "customerProfileId": "9876543210",
    "maskedCardNumber": "XXXX1111",
    "cardType": "Visa",
    "expirationDate": "1227",
    "expMonth": 12,
    "expYear": 2027,
    "billingAddress": {
      "firstName": "Alex",
      "lastName": "Chen",
      "company": "Brightfield Supply Co.",
      "address1": "300 Commerce Blvd",
      "city": "Portland",
      "state": "OR",
      "zipCode": "97201",
      "country": "US"
    },
    "isDefault": true,
    "paymentProvider": "AuthorizeNet",
    "active": true
  }
}

Example response (WorldPay — redirect)

{
  "requiresRedirect": true,
  "redirectUrl": "https://certtransaction.hostedpayments.com/?TransactionSetupID=XYZ987ABC654",
  "provider": "WorldPay",
  "paymentMethod": null
}

When requiresRedirect is true, redirect the customer’s browser to redirectUrl:

if (response.requiresRedirect) {
  window.location.href = response.redirectUrl;
}

WorldPay payment callback

WorldPay posts to this endpoint after a hosted payment transaction completes (successfully or otherwise). Do not call this endpoint directly from your application — it is called by WorldPay’s payment infrastructure after every transaction initiated via POST /api/payments/worldpay/transaction-setup. When Nymble Commerce receives a successful callback, it:

Records the payment against the associated invoice.
Updates the invoice status to PartiallyPaid or Paid.
Saves the card as a payment method if the customer opted in during the hosted page flow.

Document this endpoint if you operate a proxy or firewall in front of the Nymble Commerce API. You must allow inbound POST requests from WorldPay’s IP ranges to this path.

What WorldPay sends

WorldPay posts a form-encoded payload containing the TransactionSetupID, approval code, card details, and transaction result. Nymble Commerce validates the payload against the original transaction setup and processes the result accordingly. You do not need to handle or forward this callback — it is consumed entirely by Nymble Commerce. Your application is notified of the result via the ApplicationReturnUrl redirect you supplied when creating the transaction setup.

​Hosted payment flow

​Saved payment methods

​The payment method object

​Endpoints

​Initiate a hosted payment session

​Request body

​Example request

​Response

​Example response

​Get saved payment methods for a customer

​Path parameters

​Example request

​Response

​Save a payment method

​Request body

​Example request (Authorize.Net — direct)

​Example request (WorldPay — redirect)

​Response

​Example response (Authorize.Net — direct)

​Example response (WorldPay — redirect)

​WorldPay payment callback

​What WorldPay sends

Hosted payment flow

Saved payment methods

The payment method object

Endpoints

Initiate a hosted payment session

Request body

Example request

Response

Example response

Get saved payment methods for a customer

Path parameters

Example request

Response

Save a payment method

Request body

Example request (Authorize.Net — direct)

Example request (WorldPay — redirect)

Response

Example response (Authorize.Net — direct)

Example response (WorldPay — redirect)

WorldPay payment callback

What WorldPay sends