Card Payment Quickstart

Authorization

With each API call, you must set request headers including an OAuth 2.0 access token.

Use the OAuth request to get an access token for use with your subsequent API calls. Include the terminalKey:terminalSecret as your Basic Auth credentials.

Authorization Example

Sample request command:

curl -v https://naspay.com/auth/token \
  -X GET \
  -H "Accept: application/json" \
  -u "<terminalKey>:<terminalSecret>" \
  -d "grant_type=client_credentials"

Sample response:

{
    "access_token": "f3ca90fc-f492-4ff3-872a-5f0b84a09445",
    "token_type": "bearer"
}

The obtained access_token should be provided in "Auhorization" HTTP header in subsequent API requests, e.g.:

Authorization: Bearer <access_token>

Errors

Naspay uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a transaction declined, etc.), and codes in the 5xx range indicate an error with Naspay servers (these are rare). In erroneous cases, server response will contain “error” object with detailed information about the error.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a card is declined), server return a 422 error code (“Unprocessable Entity”). To understand why a card is declined, refer to the list of result codes.

Create payment in Hosted Payment Page mode

In the following example a create transaction request is posted for merchant terminal operating in Hosted Payment Page mode.

The minimal payment request contains following fields:

  • amount – transaction amount
  • currency – code of the transaction currency
  • merchantTransactionId – Unique ID of the transaction assigned by Merchant
  • description – Description of the payment

Example:

{
    "amount": 12.98,
    "currency": "EUR",
    "merchantTransactionId": "ORDER-12345",
    "description": "Purchase 9 red roses"
}

If paymentMethod is not specified, the CREDIT_CARD will be used. For payment methods other then CREDIT_CARD the customer’s email address must be specified.

Example PayPal request:

{
    "paymentMethod": "PAYPAL",
    "amount": 12.98,
    "currency": "EUR",
    "merchantTransactionId": "ORDER-12345",
    "description": "Purchase 9 red roses",
    "customer": {
      "email": "john@example.com"
    }
}

Http request must contain the access_token obtained during authorization.

Full request command example:

curl -v https://naspay.com/api/v1/transactions \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
        "intent": "SALE",
      	"amount": 115.01,
      	"currency": "USD",
      	"merchantTransactionId": "tx-d4345dd2a0e",
      	"description": "Test Purchase via PaymentPage",
      	"shippingAddress": {
          "line1": "12, Sunrise Street",
          "line2": "Office 1234",
      	  "city": "Fremont",
      	  "countryCode": "US",
      	  "postalCode": "94536",
      	  "state": "CA",
      	  "phone": "(123) 456-7890",
      	  "recipientName": "John Smith"
        },
        "customer": {
          "email": "john@example.com",
          "phone": "(123) 456-7890",
          "merchantCustomerId": "cus-123456",
          "locale": "en",
          "ip": "99.33.51.102"
        }
      }'

Response example:

{
    "id": "9771fe8e1b4a4ce5b5f51c8681b58985",
    "created": "2017-01-11T08:49:36.524Z",
    "updated": "2017-01-11T08:49:36.524Z",
    "state": "CREATED",
    "paymentMethod": "CREDIT_CARD",
    "amount": 115.01,
    "currency": "USD",
    "merchantTransactionId": "tx-d4345dd2a0e",
    "description": "Test Purchase via PaymentPage",
    "shippingAddress": {
        "line1": "12, Sunrise Street",
        "line2": "Office 1234",
        "city": "Fremont",
        "state": "CA",
        "postalCode": "94536",
        "countryCode": "US",
        "phone": "(123) 456-7890",
        "recipientName": "John Smith"
    },
    "links": [
        {
            "href": "https://naspay.com/api/v1/transactions/9771fe8e1b4a4ce5b5f51c8681b58985",
            "rel": "self"
        },
        {
            "href": "https://naspay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
            "rel": "payment"
        },
        {
            "href": "https://naspay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
            "rel": "checkout"
        }
    ]
}

To proceed with the payment the Customer should be redirected to checkout URL. The self URL can be used to check transaction status via API while payment URL can be used by the Customer as a permanent transaction URL.

Create payment in Server-to-Server mode

In the following example a create transaction request is posted for merchant terminal operating in Server-to-Server mode. For payment methods other then CREDIT_CARD the request is the same as used in Hosted Payment Page mode. For CREDIT_CARD payment method the card data must be provided.

The minimal payment request contains following fields:

  • amount – transaction amount
  • currency – code of the transaction currency
  • merchantTransactionId – Unique ID of the transaction assigned by Merchant
  • description – Description of the payment
  • card – element containing card data

Example:

{
    "amount": 12.98,
    "currency": "EUR",
    "merchantTransactionId": "ORDER-12345",
    "description": "Purchase 9 red roses",
    "card": {
        "pan": "4000 0000 0000 0408",
        "expiryMonth": 11,
        "expiryYear": 2023,
        "cardholder": "Mr. Holder",
        "cvv": "123"
    }
}

Http request must contain the access_token obtained during authorization.

Full request command example:

curl -v https://naspay.com/api/v1/transactions \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
        "intent": "SALE",
      	"amount": 115.01,
      	"currency": "USD",
      	"merchantTransactionId": "tx-d4345dd2a0e",
      	"description": "Test Purchase in StS mode",
      	"shippingAddress": {
          "line1": "12, Sunrise Street",
          "line2": "Office 1234",
      	  "city": "Fremont",
      	  "countryCode": "US",
      	  "postalCode": "94536",
      	  "state": "CA",
      	  "phone": "(123) 456-7890",
      	  "recipientName": "John Smith"
        },
        "customer": {
          "email": "john@example.com",
          "phone": "(123) 456-7890",
          "merchantCustomerId": "cus-123456",
          "locale": "en",
          "ip": "99.33.51.102"
        },      
        "card": {
          "pan": "4000 0000 0000 0408",
          "expiryMonth": 11,
          "expiryYear": 2023,
          "cardholder": "Mr. Holder",
          "cvv": "123",
          "billingAddress": {
            "line1": "required first line",
            "line2": "optional second line",
            "city": "Saratoga",
            "countryCode": "US",
            "postalCode": "95070",
            "state": "CA",
            "phone": "123456789"
          }
        }
      }'

Note that card.billingAddress, customer.email, customer.phone can be mandatory for your integration. Please consult Naspay customer support for details.

Response example:

{
    "id": "9771fe8e1b4a4ce5b5f51c8681b58985",
    "created": "2017-01-11T08:49:36.524Z",
    "updated": "2017-01-11T08:49:36.524Z",
    "state": "IN_PROGRESS",
    "paymentMethod": "CREDIT_CARD",
    "amount": 115.01,
    "currency": "USD",
    "merchantTransactionId": "tx-d4345dd2a0e",
    "description": "Test Purchase in StS mode",
    "shippingAddress": {
        "line1": "12, Sunrise Street",
        "line2": "Office 1234",
        "city": "Fremont",
        "state": "CA",
        "postalCode": "94536",
        "countryCode": "US",
        "phone": "(123) 456-7890",
        "recipientName": "John Smith"
    },
    "links": [
        {
            "href": "https://naspay.com/api/v1/transactions/9771fe8e1b4a4ce5b5f51c8681b58985",
            "rel": "self"
        },
        {
            "href": "https://naspay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8",
            "rel": "payment"
        },
        {
            "href": "https://naspay.com/payment/c0b491d9-bb7e-440d-9b4e-5c232bf3a8b8/redirect",
            "rel": "checkout"
        }
    ]
}

If checkout link is present and state is IN_PROGRESS the Customer must be redirected to checkout URL to proceed with payment. The self URL can be used to check transaction status via API while payment URL can be used by the Customer as a permanent transaction URL.

Backoffice Operations

You can perform different types of backoffice operations using our server-to-server REST API.

  • Capture an authorization
  • Reverse an authorization (void)
  • Refund a payment

Capture an authorization

This operation is used to capture authorized funds. To use this operation, the original payment call must have the intent set to AUTHORIZE. A capture request is performed against a previously authorized payment transaction.

Request sample

curl https://naspay.com/api/v1/transactions/<transactionId>/actions/capture \
  -X POST \
  -H "Accept: application/json" \    
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>"

Response sample

{
    "id": "d7993562260c4ec2904612e5aa787261",
    "created": "2017-01-10T09:37:43Z",
    "updated": "2017-01-10T09:37:56Z",
    "state": "COMPLETED"
}

Reverse an authorization (void)

This operation is used to release funds that the authorization holds. To use this operation, the original payment call must have the intent set to AUTHORIZE. A void request is performed against a previously authorized payment transaction.

Request sample

curl https://naspay.com/api/v1/transactions/<transactionId>/actions/void \
  -X POST \
  -H "Accept: application/json" \    
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>"

Response sample

{
    "id": "d7993562260c4ec2904612e5aa787261",
    "created": "2017-01-10T09:37:43Z",
    "updated": "2017-01-10T09:37:56Z",
    "state": "VOIDED"
}

Refund a payment

This operation is used to fully or partially refund COMPLETED payment. Several refunds can be created for one payment, but total refunded amount cannot exceed amount of initial payment transaction.

curl https://naspay.com/api/v1/transactions/<transactionId>/actions/refund \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
        "amount": 10,
        "comment":"Refund reason"
      }'

Response sample

{
    "id": "801fb13afafb4db3b31d61617a29c930",
    "created": "2017-01-11T10:09:26.179Z",
    "updated": "2017-01-11T10:09:26.179Z",
    "state": "COMPLETED",
    "amount": 10,
    "currency": "USD",
    "description": "Refund reason",
    "paymentTransactionId": "b14d79b2ddd84a639499bfda64980de8",
    "links": [
        {
            "href": "https://naspay.com/api/v1/transactions/801fb13afafb4db3b31d61617a29c930",
            "rel": "self"
        }
    ]
}

Return Urls

When transaction processing is completed or cancelled, Customer is redirected back to the merchant’s website. Merchant may provide URLs to handle different use-cases. It may be configured via Merchant Portal.

Type Description Required Example
ShopUrl The base URL of the shop. It will be used if more specific urls not specified. Yes https://shop.example.com
ReturnSuccessUrl Customer will be redirected to this URL when transaction is AUTHORIZED or COMPLETED (depending on Payment Intent) No /checkout/${merchantTransactionId}?success
ReturnFailureUrl Customer will be redirected to this URL when transaction is DECLINED No /checkout/${merchantTransactionId}?decline
ReturnHoldUrl Customer will be redirected to this URL when transaction is ON_HOLD (should be captured manually) No /checkout/${merchantTransactionId}?on_hold
ReturnCancelUrl Customer will be redirected to this URL when he/she clicks on the “Cancel” on the hosted payment page No /checkout/${merchantTransactionId}?cancel

ReturnSuccessUrl, ReturnFailureUrl and ReturnCancelUrl must be relative to ShopUrl or must be in the same domain. URLs may contain a placeholders (see Url Placeholders).

URL Placeholders

URLs may contain placeholders which will be resolved before actual redirect.

Following expressions are supported:

  • ${merchantTransactionId} – Merchant transaction ID provided in Create Transaction operation

Example:

The URL https://www.example.com/payment/${merchantTransactionId}/success will be resolved to https://www.example.com/payment/ORDER-123/success for transaction with merchantTransactionId=ORDER-123