Payment Methods

The Payment Methods API allows you to tokenize card data. This process replaces sensitive information (like the full card number) with a unique, non-sensitive identifier known as a token (id).

This step is fundamental to ensuring maximum security and simplifying your compliance with the PCI DSS standard. By operating with tokens, the actual card data never touches your servers, which minimizes risk and protects your customers' information.

You can use these tokens to securely process charges, either for one-time transactions or to link them to subscriptions, without needing to request the card details again.

---

Features

Authentication and Security

To access the API, it is necessary to authenticate each request with a token, see Authentication.

📌 Create payment method.

• Base URL: https://api-sandbox.n1co.shop
• Method: POST
• Endpoint: /api/v3/PaymentMethods
• Description: Create a payment method to tokenize card data.
• Required headers:
• Content-Type: application/json
• Authorization: Bearer {your_token}
• Example:

Request

{
    "customer": {
        "id": "customer001",
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phoneNumber": "+50364331900"
    },
    "card": {
        "number": "4000000000002701",
        "cardHolder": "CARLOS DURAN",
        "expirationMonth": "10",
        "expirationYear": "2028",
        "cvv": "111",
        "singleUse": false
    }
}

Response

{
    "id": "69167196381d34f25eb22e9d",
    "type": "card",
    "bin": {
        "brand": "visa",
        "issuerName": "INTL HDQTRS-CENTER OWNED",
        "countryCode": "SLV"
    },
    "success": true,
    "message": "The payment method was created successfully"
}

- Request Parameters

Parameter	Type	Required	Description
customer	object	✅	Object containing customer information.
customer.id	string	✅	Unique identifier for your customer.
customer.name	string	✅	Customer's full name.
customer.email	string	✅	Customer's email.
customer.phoneNumber	string	✅	Customer's phone number (e.g., "+50364331900").
card	object	✅	Object containing card data.
card.number	string	✅	Credit or debit card number.
card.cardHolder	string	✅	Name of the cardholder, as it appears on the card.
card.expirationMonth	string	✅	Card's expiration month (e.g., "09").
card.expirationYear	string	✅	Card's expiration year (e.g., "2030").
card.cvv	string	✅	Card's security code (CVV, CVC).
card.singleUse	boolean	✅	Defines if the generated token will be single-use (true) or multi-use (false).

How to use card.singleUse?

This boolean parameter determines the lifespan of the generated token:

• card.singleUse: true (Recommended for One-Time Payments): The generated token will be single-use and will be automatically invalidated after being used in a charge. It is the ideal option for transactions where the customer does not want to save their card for future purchases.

• card.singleUse: false (Required for Subscriptions and Saved Cards): The token will be multi-use, allowing it to be used for multiple charges. You must use this option if you plan to:

  • Link the payment method to a subscription.
  • Save the card to a customer's profile to facilitate future purchases.

- Response Parameters

Parameter	Type	Description
id	string	The unique identifier of the payment method (token).
type	string	Type of payment method, in this case, "card".
bin	object	Object with information from the card's BIN.
bin.brand	string	The card brand (e.g., "visa", "mastercard").
bin.issuerName	string	Name of the card's issuing bank.
bin.countryCode	string	Issuing country code of the card (e.g., "SLV").
success	boolean	Indicates if the payment method creation was successful.
message	string	Descriptive message of the operation's result.

---

📌 Update payment method.

• Base URL: https://api-sandbox.n1co.shop
• Method: PUT
• Endpoint: /api/v3/PaymentMethods
• Description: Update payment method.
• Required headers:
• Content-Type: application/json
• Authorization: Bearer {your_token}
• Example:

Request

{
    "customerId": "customer001",
    "cardId": "69167196381d34f25eb22e9d",
    "card": {
        "cardHolder": "CARLOS DURAN",
        "expirationMonth": "12",
        "expirationYear": "2030",
        "cvv": "111"
    }
}

Response

{
    "id": "69167196381d34f25eb22e9d",
    "type": "card",
    "bin": {
        "brand": "visa",
        "issuerName": "INTL HDQTRS-CENTER OWNED",
        "countryCode": "SLV"
    },
    "success": true,
    "message": "The payment method was updated"
}