Cost+Docs

Quickstart

Accept your first payment in 5 minutes

This guide walks you through creating and completing a test payment using the Cost+ API. By the end, you'll have a working integration you can build on.

Prerequisites

Not sure how to get your API key? See Testing Your Integration for detailed setup instructions.

Step 1: Create an Order

Send a POST request to create a payment order. Replace YOUR_API_KEY with your sandbox API key:

Create an order
curl -X POST https://api.costplus.online/v1/orders/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 1295,
    "merchant_order_id": "my-first-order",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

The amount is in the smallest currency unit (cents). 1295 means 12.95 EUR.

The API returns the full order object. The key fields are id, status, and the payment_url inside the transaction:

Response
{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "description": "Test order",
  "return_url": "https://example.com/return",
  "webhook_url": "https://example.com/webhook",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Save the id — you'll need it in Step 3.

Step 2: Complete the Test Payment

  1. Open the payment_url from the response in your browser
  2. On the payment page, enter the test card details:
FieldValue
Card number4111 1111 1111 1111
ExpiryAny future date (e.g. 12/28)
CVCAny 3 digits (e.g. 123)
  1. Submit the payment
  2. You'll be redirected back to your return_url

Don't rely on the redirect alone to confirm payment. The customer may close their browser before being redirected. Always verify via the API (Step 3) or webhooks (Step 4).

Step 3: Verify the Payment

Fetch the order to confirm it completed:

Check order status
curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

A successful payment looks like this:

Response (completed)
{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "completed": "2026-01-15T12:02:30.123456+00:00",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "completed",
      "amount": 1295,
      "currency": "EUR",
      "payment_method_details": {
        "truncated_pan": "1111",
        "card_expiry": "122028"
      }
    }
  ]
}

The order status is "completed" — the payment was successful.

When the payment status changes, Cost+ sends a POST request to your webhook_url:

Webhook payload
{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

When you receive this:

  1. Call GET /v1/orders/{order_id}/ to verify the current status (never trust the webhook payload alone)
  2. Return HTTP 200 to acknowledge receipt
  3. Fulfill the order if the status is "completed"

For local development, use a tunnel like ngrok to expose your local server and receive webhooks.

See the Webhooks guide for retry logic, best practices, and payload details.

If you don't need server-side redirect logic, payment links offer a simpler path. Create a link, share the URL with your customer, and check the status later.

Create a payment link
curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 2500,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

The response includes a payment_url you can share via email, SMS, or chat. The customer can attempt payment multiple times (up to 25) until the link expires or payment succeeds.

See the Payment Links guide for the full workflow.

What's Next?

You've completed your first payment. Here's where to go from here:

  • Hosted Payment Page — full HPP reference with all request fields and options
  • Recurring Payments — set up subscriptions and scheduled billing
  • One-Click Payments — fast checkout for returning customers
  • Auth / Capture / Void — authorize first, capture later (e.g. when shipping)
  • Refunds — process full and partial refunds
  • SDKs — official libraries for Node.js, Python, PHP, Java/Kotlin, C#/.NET, and Ruby
  • Plugins — pre-built integrations for Shopify, WooCommerce, Magento, and more

On this page

PrerequisitesStep 1: Create an OrderStep 2: Complete the Test PaymentStep 3: Verify the PaymentStep 4: Handle the Webhook (Recommended)Alternative: Payment LinksWhat's Next?Related Endpoints