# Create Payment Method

## **Introduction** <a href="#migrationtopaymentsapi-createpaymentmethod" id="migrationtopaymentsapi-createpaymentmethod"></a>

This endpoint is used to create a new payment method for a Subscriber using either a Credit Card or a Bank Account and to create a new record in the *PaymentMethod* table in the database.

## Comparison <a href="#migrationtopaymentsapi-comparison.4" id="migrationtopaymentsapi-comparison.4"></a>

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

{% hint style="success" %}
**Note:** *For the time being, both the old and new endpoints are in the Billing API.*
{% endhint %}

<table data-full-width="true"><thead><tr><th width="141.33333333333331"> </th><th width="434">Billing API (OLD)</th><th>Billing API (NEW)</th></tr></thead><tbody><tr><td>URL</td><td>/Billing/{subscriptionId}/PaymentMethods</td><td>/Billing/PaymentMethods</td></tr><tr><td><strong>Method</strong></td><td>POST</td><td>POST</td></tr><tr><td><strong>Input Example</strong></td><td><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
   "PaymentMethod":{
      "PaymentMethodId":0,
      "ExternalPaymentMethodId":"10203992",
      "PaymentMethodType":1,
      "PaymentMethodTypeName":"CreditCard",
      "PlatformSpecificTypeName":null,
      "AccountHolder":"EARL HROZA",
      "CreditCard":{
         "CardType":2,
         "CreditCardType":2,
         "CreditCardNumber":"XXXXXXXXXXXX1111",
         "ExpirationYear":2028,
         "ExpirationMonth":2,
         "CardSecurityCode":"",
         "CardOwner":"john smith",
         "LastFourDigits":"1111"
      },
      "BankAccount":null,
      "PayPalInfo":null,
      "OfflinePayment":null,
      "BillingAddress":{
         "AddressId":1700202,
         "BillingSystemAddressId":null,
         "PrimaryAddress":null,
         "AlternateAddresses":null,
         "CountryName":null,
         "CityName":null,
         "DistrictName":null,
         "ProvinceOrTerritory":null,
         "PhoneNumber":null,
         "ZipCode":null,
         "AddressName":null
      },
      "PaymentSource":null,
      "TermsAndConditionsAccepted":true,
      "ExternalToken":"10203992",
      "ExternalCustomerId":null,
      "IsDefault":false
   },
   "BillingAddressId":1700202,
   "ValidateAddress":null,
   "AccountInfo":{
      "SubscriptionId":245316,
      "SubscriberId":4784,
      "RegistrationId":0
   }
}
</code></pre></td><td><p>Credit Card example:</p><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
  "HolderName": "Clark Kent",
  "CreditCard": {
    "CreditCardExpirationMonth": "06",
    "CreditCardExpirationYear": "12",
    "CreditCardNumber": "4111********1111",
    "CreditCardType": 1
  },
  "BillingAddressId": 1859629,
  "BillingSystemPaymentMethodId": "test",
  "PaymentGatewayToken": "ASFWE234234",
  "PaymentGatewayCustomerId": "HKUSDYISD"
  "SubscriptionId": 20,
  "PaymentMethodType": 1
}
</code></pre><p>BankAccount example:</p><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
  "HolderName": "Bruce Wayne",
  "BankAccount": {
    "BankAccountNumber": "123456",
    "BankAccountType": 1,
    "BankName": "Gotham City Bank",
    "BankRoutingNumber": "3456324"
  },
  "BillingAddressId": 0,
  "SubscriptionId": 20,
  "PaymentMethodType": 2
}
</code></pre></td></tr></tbody></table>

***

## Create Payment Method

<mark style="color:green;">`POST`</mark> `/Billing/PaymentMethods`

This endpoint is used to create a new payment method for a Subscriber using either a Credit Card or a Bank Account and to create a new record in the *PaymentMethod* table in the database.

**Note:** *The parameters marked with an asterisk* (<mark style="color:red;">\*</mark>) *are mandatory and must be included in the input model.*

#### Headers

| Name                                               | Type   | Description                                   |
| -------------------------------------------------- | ------ | --------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark>    | String | JSON Web Token used for security purposes     |
| X-SourceSystem<mark style="color:red;">\*</mark>   | String | To identify the consumer or the Source System |
| X-MediaGroupCode<mark style="color:red;">\*</mark> | String | Media Group Code of the Tenant                |
| X-ClientCode<mark style="color:red;">\*</mark>     | String | Client Code of the Tenant                     |
| X-PaperCode<mark style="color:red;">\*</mark>      | String | Paper Code of the Tenant                      |

#### Request Body

| Name                                             | Type    | Description                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SubscriptionId<mark style="color:red;">\*</mark> | Integer | Unique identifier of the Subscription in Naviga System                                                                                                                                                                                                                                                     |
| BillingAddressId                                 | Integer | Unique identifier of the current Subscriber Billing address in Naviga System.                                                                                                                                                                                                                              |
| BillingSystemPaymentMethodId                     | String  | <p>Unique identifier of the payment method in Naviga System.</p><p>(Used by the data team.)</p>                                                                                                                                                                                                            |
| HolderName<mark style="color:red;">\*</mark>     | String  | For a Bank Account payment method, it’s the Subscriber’s name, and for a Credit Card payment method, it’s the Credit Card name.                                                                                                                                                                            |
| CreditCard.CreditCardType                        | Integer | Represents the credit card type. Possible values: American Express (1), Visa (2), MasterCard (3), Diners (4), Discover (5).                                                                                                                                                                                |
| CreditCard.CreditCardNumber                      | String  | <p>Masked Credit Card number.</p><p>Required if Payment Method is Credit Card.</p>                                                                                                                                                                                                                         |
| CreditCard.CreditCardExpirationYear              | Integer | <p>Credit card expiration year.</p><p>Required if Payment Method is Credit Card.</p>                                                                                                                                                                                                                       |
| CreditCard.CreditCardExpirationMonth             | Integer | <p>Credit card expiration month.</p><p>Required if Payment Method is Credit Card.</p>                                                                                                                                                                                                                      |
| BankAccount.BankAccountNumber                    | String  | <p>Bank account number.</p><p>Required if Payment Method is Bank Account.</p>                                                                                                                                                                                                                              |
| BankAccount.BankName                             | String  | <p>Name of the bank.</p><p>Required if Payment Method is Bank Account.</p>                                                                                                                                                                                                                                 |
| BankAccount.BankAccountType                      | Integer | <p>Represents the bank account type.</p><p>Required if Payment Method is Bank Account.</p><p></p><p>Possible values: CheckingsAccount(1), SavingsAccount (2), CorporateCheckingsAccount(3).</p>                                                                                                            |
| PaymentMethodType                                | Integer | <p>Represents the payment method type.</p><p></p><p>Possible values: CreditCard(1), BankAccount(2), MerchantAcceptedPayment(3), Coupon(4), PayPal(5), PayPalExpress(6), iTunes(7), GooglePlay(8), ApplePay(9), AmazonInApp(10), SubscribeWithGoogle(11), GooglePay(12), ExternalPayment(13), Piano(14)</p> |
| PaymentGatewayCustomerId                         | String  | <p>Unique identifier of the Payment Method’s owner in the Payment Gateway Systems.</p><p>Required if Payment Method is Credit Card.</p><p></p><p><strong>Note:</strong> <em>This parameter is not managed by all payment gateways; however, Stripe, Braintree, and NavigaPay do.</em></p><p></p>           |
| PaymentGatewayToken                              | String  | <p>Unique identifier of the Payment Method in the Payment Gateway Systems (Payway, AuthorizeNET, Stripe, Braintree, NavigaPay, etc).</p><p>Required (and mandatory) if Payment Method is Credit Card.</p>                                                                                                  |
| PaymentMethod.CreditCard.CardOwner               | String  | <p>Credit card Owner name.</p><p>Required if Payment Method is Credit Card.</p>                                                                                                                                                                                                                            |
| BankAccount.BankRoutingNumber                    | String  | <p>Bank account routing number.</p><p>Required if Payment Method is Bank Account.</p>                                                                                                                                                                                                                      |

{% tabs %}
{% tab title="200: OK Success Response" %}

```json
{
  "Code": 200,
  "Errors": [],
  "Result": {
    "PaymentMethodId": 789507
  },
  "SessionId": null,
  "RequestId": null
}
```

{% endtab %}

{% tab title="400: Bad Request Invalid Input" %}

```json
{
   "Code":400,
   "Errors":[
      {
         "Message":"Invalid inputs.",
         "Code":"BILLING_01",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}
```

{% endtab %}

{% tab title="400: Bad Request Subscription not found." %}

```json
{
   "Code":400,
   "Errors":[
      {
         "Message":"Subscription not found.",
         "Code":"Billing_01",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}
```

{% endtab %}

{% tab title="400: Bad Request Billing Address not found." %}
{% code overflow="wrap" %}

```json
{
   "Code":400,
   "Errors":[
      {
         "Message":"Billing Address not found.",
         "Code":"Billing_03",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Error getting newspaper configuration settings." %}
{% code overflow="wrap" fullWidth="false" %}

```json
{
   "Code":500,
   "Errors":[
      {
         "Message":"Error getting newspaper configuration settings.",
         "Code":"Billing_02",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Failed to create ADDPAYMENTMETHOD Event." %}

```json
{
   "Code":500,
   "Errors":[
      {
         "Message":"Failed to create ADDPAYMENTMETHOD Event.",
         "Code":"Billing_04",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}
```

{% endtab %}

{% tab title="400: Bad Request Failed to update ADDPAYMENTMETHOD Event." %}
{% code overflow="wrap" %}

```json
{
   "Code":500,
   "Errors":[
      {
         "Message":"Failed to update ADDPAYMENTMETHOD Event.",
         "Code":"Billing_05",
         "Type":{
            "Id":1,
            "Code":"NotProcessingAllowed"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request Failed when saving Payment Method to DB" %}

```json
{
   "Code":400,
   "Errors":[
      {
         "Message":"Failed when saving Payment Method to DB.",
         "Code":"Billing_06",
         "Type":{
            "Id":0,
            "Code":"Validation"
         },
         "ErrorSource":null
      }
   ],
   "Result":null,
   "SessionId":"string",
   "RequestId":"string"
}
```

{% endtab %}

{% tab title="400: Bad Request Authorization is missing" %}

```json
{
    "error": "Authorization is missing."
}

```

{% endtab %}

{% tab title="400: Bad Request X-SourceSystem is missing" %}

```json
{
    "error": "X-SourceSystem is missing."
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid Source System" %}

```json
{
    "error": "Invalid Source System."
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid authorization" %}

```json
{
    "error": "Invalid authorization."
}
```

{% endtab %}

{% tab title="500: Internal Server Error Internal Server Error" %}

```json
{
    "error": "Something went wrong. Please try again later."
}
```

{% endtab %}
{% endtabs %}