FAQ

AuthenticationCopy Anchor Link

Why do I get 401 Unauthorized?Copy Anchor Link

Your API key is wrong or missing. Every request must authenticate with HTTP Basic authentication: your API key is the username and the password is empty. If you build the Authorization header yourself, Base64-encode your API key followed by a colon (:).

Also check that you use the API key of the right project: a test project and a live project each have their own key. See API basics.

Payment methodsCopy Anchor Link

Why is my order rejected with 400 Bad Request when I select a payment method?Copy Anchor Link

The payment method probably isn't active for your project. You apply for each payment method separately, and can only use it once Paytrim has activated it. An order with a payment method that isn't active, or that doesn't exist, is rejected with an error.

For example, this order for credit-card is rejected when cards aren't active for your project:

curl https://api.pay.paytrim.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "merchant_order_id": "EXAMPLE001",
    "amount": 995,
    "currency": "EUR",
    "description": "Example order #1",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

See Payment methods for the payment methods you can offer.

Payment statusCopy Anchor Link

How do I check the status of a payment?Copy Anchor Link

Retrieve the order with GET /v1/orders/{order_id}/. Check, in this order:

1. The order status: required for the hosted payment page.
2. The status of the transaction in the transactions array.
3. The response code of the processor in outcomes.processing.response_code.

A payment succeeded when the order status is completed, the transaction status is accepted and the response code is 00. You can deliver.

{
  "status": "completed",
  "transactions": [
    {
      "status": "accepted",
      "payment_method": "credit-card",
      "payment_method_brand": "mastercard",
      "outcomes": {
        "processing": {
          "response_code": "00",
          "status": "accepted"
        }
      }
    }
  ]
}

The response is shortened. See Order and transaction status for every status.

Why did a payment fail?Copy Anchor Link

A failed payment returns either:

• HTTP 200 with transaction status error: the payment was declined;
• HTTP 4xx or 5xx: the request failed for technical reasons. See API basics.

For a declined payment, look at:

1. outcomes.processing.response_code and outcomes.processing.response_code_description;
2. the reason field, see Error reasons;
3. the events array of the transaction.

Some common causes:

In this example, the card issuer declined the payment with response code 05, "Do not honor". Don't deliver.

{
  "status": "error",
  "transactions": [
    {
      "status": "error",
      "payment_method": "credit-card",
      "outcomes": {
        "processing": {
          "response_code": "05",
          "response_code_description": "Do not honor",
          "status": "error"
        }
      },
      "events": [
        {
          "event": "processing",
          "result": "declined"
        }
      ]
    }
  ]
}

Why do I get HTTP 200 while the transaction status is error?Copy Anchor Link

That's expected. HTTP 200 means your request was valid and Paytrim processed it. The transaction status error means the result was negative, for example because the issuer declined the card.

Why is my payment stuck in processing?Copy Anchor Link

A payment can stay processing for a while because of delays at the issuer, network routing or fraud checks. Retrieve the order every 30 to 60 seconds, and allow up to a few minutes depending on the issuer. Don't retry the payment until the transaction status is error.

What does pending mean?Copy Anchor Link

Your customer is completing 3-D Secure authentication. Wait until they finish, or wait for the webhook.

How do I know my customer cancelled?Copy Anchor Link

The transaction status is cancelled, and the transaction has a cancelled event.

How do I know 3-D Secure failed?Copy Anchor Link

The transaction fails, and contains:

{
  "received_3ds_authentication": {
    "result": "failed"
  }
}

See 3D Secure and the 3-D Secure error reasons.

How do I know my customer is back after 3-D Secure?Copy Anchor Link

Your customer is redirected to your return_url. That redirect doesn't tell you the result: confirm the status by retrieving the order, or wait for the webhook.

WebhooksCopy Anchor Link

What happens when my webhook endpoint is down?Copy Anchor Link

Paytrim retries a failed webhook every 2 minutes, up to 10 attempts. See Webhooks.

Are there other callbacks besides webhooks?Copy Anchor Link

No. Besides webhooks, Paytrim doesn't send callbacks. Retrieve the order to check its status.

CardsCopy Anchor Link

How long is a vault_token valid?Copy Anchor Link

Until the issuer invalidates the card. Store vault tokens securely and only use them from your server.

What's the difference between a sale and an authorization?Copy Anchor Link

• Sale: the money is captured immediately.
• Authorization: the money is reserved on the card and captured later. See Pre-authorizations.

The capture_mode of the transaction tells you which one it is: manual or delayed means an authorization.